feat: add clip option to screenshot for cropping to a region

README.md

@@ -137,6 +137,9 @@ mobilecli screenshot --device <device-id> --scale 0.5
 # Limit the largest dimension to 800 pixels, keeping aspect ratio
 mobilecli screenshot --device <device-id> --max-size 800
 
+# Crop to a region (x,y,width,height in screen points), applied before scaling
+mobilecli screenshot --device <device-id> --clip 10,80,300,200
+
 # Save to specific path
 mobilecli screenshot --device <device-id> --output screenshot.png
 

agents/android/java/Screenshot.java

@@ -24,10 +24,13 @@
  * Usage:
  *   adb shell CLASSPATH=/data/local/tmp/mobilecli.dex app_process / \
  *     com.mobilenext.mobilecli.Screenshot [--format png|jpeg] [--quality 1-100] \
- *     [--scale 0.0-1.0] [--max-size N]
+ *     [--scale 0.0-1.0] [--max-size N] [--clip x,y,w,h --screen-width N]
  *
  * --max-size caps max(width, height) at N pixels keeping aspect ratio and
  * takes precedence over --scale. Neither ever upscales.
+ * --clip crops to the given rect (in screen points) before scaling;
+ * --screen-width (screen width in points) is required with it to map
+ * points to pixels of the captured bitmap.
  */
 public class Screenshot {
 
@@ -38,6 +41,8 @@ public static void main(String[] args) {
 			double scale = 1.0;
 			int maxSize = 0;
 			String outPath = null;
+			int[] clip = null;
+			int screenWidth = 0;
 
 			for (int i = 0; i + 1 < args.length; i += 2) {
 				String flag = args[i];
@@ -50,6 +55,10 @@ public static void main(String[] args) {
 					scale = Double.parseDouble(value);
 				} else if (flag.equals("--max-size")) {
 					maxSize = Integer.parseInt(value);
+				} else if (flag.equals("--clip")) {
+					clip = parseClip(value);
+				} else if (flag.equals("--screen-width")) {
+					screenWidth = Integer.parseInt(value);
 				} else if (flag.equals("--out")) {
 					outPath = value;
 				} else {
@@ -59,6 +68,9 @@ public static void main(String[] args) {
 
 			exemptHiddenApis();
 			Bitmap bitmap = takeScreenshot();
+			if (clip != null) {
+				bitmap = clipBitmap(bitmap, clip, screenWidth);
+			}
 			bitmap = resize(bitmap, scale, maxSize);
 
 			Bitmap.CompressFormat compressFormat = format.equals("jpeg")
@@ -171,6 +183,42 @@ private static void connect(UiAutomation automation) throws Exception {
 		}
 	}
 
+	private static int[] parseClip(String value) {
+		String[] parts = value.split(",", -1);
+		if (parts.length != 4) {
+			throw new IllegalArgumentException("invalid --clip, expected x,y,width,height");
+		}
+		int[] clip = new int[4];
+		for (int i = 0; i < 4; i++) {
+			clip[i] = Integer.parseInt(parts[i]);
+		}
+		return clip;
+	}
+
+	// Crops to clip {x, y, width, height} given in screen points, mapped to
+	// bitmap pixels via screenWidthPoints. Rects partially outside the bitmap
+	// are clamped (UI hierarchy bounds can overhang the screen); rects fully
+	// outside are an error. Mirrors cropRectInPixels in utils/image.go.
+	private static Bitmap clipBitmap(Bitmap bitmap, int[] clip, int screenWidthPoints) {
+		if (clip[2] <= 0 || clip[3] <= 0) {
+			throw new IllegalArgumentException("clip width and height must be positive");
+		}
+		if (screenWidthPoints <= 0) {
+			throw new IllegalArgumentException("--screen-width is required with --clip");
+		}
+
+		double factor = (double) bitmap.getWidth() / screenWidthPoints;
+		int left = Math.max(0, (int) Math.round(clip[0] * factor));
+		int top = Math.max(0, (int) Math.round(clip[1] * factor));
+		int right = Math.min(bitmap.getWidth(), (int) Math.round((clip[0] + clip[2]) * factor));
+		int bottom = Math.min(bitmap.getHeight(), (int) Math.round((clip[1] + clip[3]) * factor));
+
+		if (right <= left || bottom <= top) {
+			throw new IllegalArgumentException("clip rect is outside the screenshot bounds");
+		}
+		return Bitmap.createBitmap(bitmap, left, top, right - left, bottom - top);
+	}
+
 	// maxSize caps max(width, height) and wins over scale; never upscales.
 	private static Bitmap resize(Bitmap bitmap, double scale, int maxSize) {
 		int width = bitmap.getWidth();

cli/screenshot.go

@@ -4,16 +4,20 @@ import (
 	"encoding/base64"
 	"fmt"
 	"os"
+	"strconv"
+	"strings"
 
 	"github.com/mobile-next/mobilecli/commands"
 	"github.com/mobile-next/mobilecli/devices"
+	"github.com/mobile-next/mobilecli/types"
 	"github.com/mobile-next/mobilecli/utils"
 	"github.com/spf13/cobra"
 )
 
 var (
 	screenshotScale      float64
 	screenshotMaxSize    int
+	screenshotClip       string
 	screencaptureScale   float64
 	screencaptureFPS     int
 	screencaptureBitrate int
@@ -24,17 +28,47 @@ const (
 	maxScreencaptureBitrate = 10_000_000
 )
 
+// parseScreenshotClip parses an "x,y,width,height" flag value (in screen
+// points); an empty value means no cropping.
+func parseScreenshotClip(value string) (*types.ScreenElementRect, error) {
+	if value == "" {
+		return nil, nil
+	}
+
+	parts := strings.Split(value, ",")
+	if len(parts) != 4 {
+		return nil, fmt.Errorf("invalid --clip %q, expected x,y,width,height", value)
+	}
+
+	numbers := make([]int, 4)
+	for i, part := range parts {
+		number, err := strconv.Atoi(part)
+		if err != nil {
+			return nil, fmt.Errorf("invalid --clip %q, expected x,y,width,height", value)
+		}
+		numbers[i] = number
+	}
+
+	return &types.ScreenElementRect{X: numbers[0], Y: numbers[1], Width: numbers[2], Height: numbers[3]}, nil
+}
+
 var screenshotCmd = &cobra.Command{
 	Use:   "screenshot",
 	Short: "Take a screenshot of a connected device",
 	Long:  `Takes a screenshot of a specified device (using its ID) and saves it locally as a PNG file. Supports iOS (real/simulator) and Android (real/emulator).`,
 	RunE: func(cmd *cobra.Command, args []string) error {
+		rect, err := parseScreenshotClip(screenshotClip)
+		if err != nil {
+			return err
+		}
+
 		req := commands.ScreenshotRequest{
 			DeviceID:   deviceId,
 			Format:     screenshotFormat,
 			Quality:    screenshotJpegQuality,
 			Scale:      screenshotScale,
 			MaxSize:    screenshotMaxSize,
+			Clip:       rect,
 			OutputPath: screenshotOutputPath,
 		}
 
@@ -157,6 +191,7 @@ func init() {
 	screenshotCmd.Flags().IntVarP(&screenshotJpegQuality, "quality", "q", 90, "JPEG quality (1-100, only applies if format is jpeg)")
 	screenshotCmd.Flags().Float64Var(&screenshotScale, "scale", 1.0, "Scale factor for screenshot (0.0-1.0)")
 	screenshotCmd.Flags().IntVar(&screenshotMaxSize, "max-size", 0, "Maximum of width/height in pixels, keeping aspect ratio (takes precedence over --scale, 0 for no limit)")
+	screenshotCmd.Flags().StringVar(&screenshotClip, "clip", "", "Crop to x,y,width,height in screen points, applied before --scale/--max-size")
 
 	// screencapture command flags
 	screencaptureCmd.Flags().StringVar(&deviceId, "device", "", "ID of the device to capture from")

cli/screenshot_test.go

@@ -0,0 +1,30 @@
+package cli
+
+import (
+	"testing"
+
+	"github.com/mobile-next/mobilecli/types"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseScreenshotClip(t *testing.T) {
+	t.Run("empty value means no cropping", func(t *testing.T) {
+		rect, err := parseScreenshotClip("")
+		require.NoError(t, err)
+		assert.Nil(t, rect)
+	})
+
+	t.Run("parses x,y,width,height", func(t *testing.T) {
+		rect, err := parseScreenshotClip("10,20,30,40")
+		require.NoError(t, err)
+		assert.Equal(t, &types.ScreenElementRect{X: 10, Y: 20, Width: 30, Height: 40}, rect)
+	})
+
+	t.Run("rejects malformed values", func(t *testing.T) {
+		for _, value := range []string{"10,20,30", "a,b,c,d", "10 20 30 40", "10,20,30,40,50", "10,20,30,40x", "10,20,30,40,"} {
+			_, err := parseScreenshotClip(value)
+			assert.Error(t, err, "value %q should be rejected", value)
+		}
+	})
+}

commands/screenshot.go

@@ -10,16 +10,18 @@ import (
 	"time"
 
 	"github.com/mobile-next/mobilecli/devices"
+	"github.com/mobile-next/mobilecli/types"
 )
 
 // ScreenshotRequest represents the parameters for taking a screenshot
 type ScreenshotRequest struct {
-	DeviceID   string  `json:"deviceId"`
-	Format     string  `json:"format,omitempty"`     // "png" or "jpeg"
-	Quality    int     `json:"quality,omitempty"`    // 1-100, only used for JPEG
-	Scale      float64 `json:"scale,omitempty"`      // 0.0-1.0, 0 or 1.0 means no scaling
-	MaxSize    int     `json:"maxSize,omitempty"`    // max(width, height) in pixels, takes precedence over Scale, 0 means no limit
-	OutputPath string  `json:"outputPath,omitempty"` // file path, "-" for stdout, or empty for default naming
+	DeviceID   string                   `json:"deviceId"`
+	Format     string                   `json:"format,omitempty"`     // "png" or "jpeg"
+	Quality    int                      `json:"quality,omitempty"`    // 1-100, only used for JPEG
+	Scale      float64                  `json:"scale,omitempty"`      // 0.0-1.0, 0 or 1.0 means no scaling
+	MaxSize    int                      `json:"maxSize,omitempty"`    // max(width, height) in pixels, takes precedence over Scale, 0 means no limit
+	Clip       *types.ScreenElementRect `json:"clip,omitempty"`       // crop rect in screen points, applied before Scale/MaxSize
+	OutputPath string                   `json:"outputPath,omitempty"` // file path, "-" for stdout, or empty for default naming
 }
 
 // ScreenshotResponse represents the response for a screenshot command
@@ -44,6 +46,27 @@ func validateScreenshotResize(scale float64, maxSize int) (float64, error) {
 	return scale, nil
 }
 
+// resolveScreenWidthForClip validates clip and returns the device screen
+// width in points, needed to map the clip rect to pixels of the captured
+// image. Returns 0 when clip is nil.
+func resolveScreenWidthForClip(device devices.ControllableDevice, clip *types.ScreenElementRect) (int, error) {
+	if clip == nil {
+		return 0, nil
+	}
+	if clip.Width <= 0 || clip.Height <= 0 {
+		return 0, fmt.Errorf("clip width and height must be positive")
+	}
+
+	info, err := device.Info()
+	if err != nil {
+		return 0, fmt.Errorf("error getting device info for clip cropping: %v", err)
+	}
+	if info.ScreenSize == nil || info.ScreenSize.Width <= 0 {
+		return 0, fmt.Errorf("device did not report a screen size, cannot crop to clip")
+	}
+	return info.ScreenSize.Width, nil
+}
+
 // ScreenshotCommand takes a screenshot of the specified device
 func ScreenshotCommand(req ScreenshotRequest) *CommandResponse {
 	// Find the target device
@@ -85,12 +108,19 @@ func ScreenshotCommand(req ScreenshotRequest) *CommandResponse {
 		return NewErrorResponse(fmt.Errorf("failed to start agent on device %s: %v", targetDevice.ID(), err))
 	}
 
-	// Take screenshot; the device is responsible for format, quality, and scaling
+	screenWidthPoints, err := resolveScreenWidthForClip(targetDevice, req.Clip)
+	if err != nil {
+		return NewErrorResponse(err)
+	}
+
+	// Take screenshot; the device is responsible for format, quality, cropping, and scaling
 	imageBytes, err := targetDevice.TakeScreenshot(devices.ScreenshotOptions{
-		Format:  req.Format,
-		Quality: req.Quality,
-		Scale:   req.Scale,
-		MaxSize: req.MaxSize,
+		Format:            req.Format,
+		Quality:           req.Quality,
+		Scale:             req.Scale,
+		MaxSize:           req.MaxSize,
+		Clip:              req.Clip,
+		ScreenWidthPoints: screenWidthPoints,
 	})
 	if err != nil {
 		return NewErrorResponse(fmt.Errorf("error taking screenshot: %v", err))

devices/android.go

@@ -262,8 +262,8 @@ func (d *AndroidDevice) captureScreenshot(displayID string) ([]byte, error) {
 }
 
 func (d *AndroidDevice) TakeScreenshot(opts ScreenshotOptions) ([]byte, error) {
-	// prefer on-device capture+encode via the embedded dex: a downscaled jpeg
-	// crosses adb instead of screencap's full-size png
+	// prefer on-device capture+encode via the embedded dex: a cropped and/or
+	// downscaled image crosses adb instead of screencap's full-size png
 	data, err := d.takeScreenshotWithDex(opts)
 	if err == nil {
 		return data, nil
@@ -274,7 +274,7 @@ func (d *AndroidDevice) TakeScreenshot(opts ScreenshotOptions) ([]byte, error) {
 	if err != nil {
 		return nil, err
 	}
-	return utils.ProcessScreenshot(data, opts.Format, opts.Quality, opts.Scale, opts.MaxSize)
+	return utils.ProcessScreenshot(data, opts.Format, opts.Quality, opts.Scale, opts.MaxSize, opts.Clip, opts.ScreenWidthPoints)
 }
 
 // takeScreenshotWithDex captures, scales, and encodes on-device via the
@@ -298,13 +298,20 @@ func (d *AndroidDevice) takeScreenshotWithDex(opts ScreenshotOptions) ([]byte, e
 
 	utils.Verbose("taking screenshot on-device via mobilecli.dex")
 
+	// all clip values are integers formatted with %d, safe to interpolate
+	clipArgs := ""
+	if opts.Clip != nil {
+		clipArgs = fmt.Sprintf(" --clip %d,%d,%d,%d --screen-width %d",
+			opts.Clip.X, opts.Clip.Y, opts.Clip.Width, opts.Clip.Height, opts.ScreenWidthPoints)
+	}
+
 	script := fmt.Sprintf(
 		"out=/data/local/tmp/mobilecli-screenshot-$$.img; "+
 			"CLASSPATH=%s app_process / com.mobilenext.mobilecli.Screenshot "+
-			"--format %s --quality %d --scale %s --max-size %d --out $out >/dev/null 2>&1; "+
+			"--format %s --quality %d --scale %s --max-size %d%s --out $out >/dev/null 2>&1; "+
 			"cat $out 2>/dev/null; rm -f $out",
 		androidDexPath, format, opts.Quality,
-		strconv.FormatFloat(opts.Scale, 'f', -1, 64), opts.MaxSize,
+		strconv.FormatFloat(opts.Scale, 'f', -1, 64), opts.MaxSize, clipArgs,
 	)
 
 	data, err := d.runAdbCommand("exec-out", script)

devices/common.go

@@ -98,11 +98,16 @@ func buildMjpegURL(port, fps int, scale float64) string {
 // ScreenshotOptions contains options for taking a screenshot.
 // MaxSize caps max(width, height) in pixels keeping aspect ratio and takes
 // precedence over Scale; neither ever upscales.
+// Rect crops before Scale/MaxSize apply; it is expressed in screen points
+// (the same units as dump.ui bounds) and mapped to pixels via
+// ScreenWidthPoints, which is required when Rect is set.
 type ScreenshotOptions struct {
-	Format  string  // "png" or "jpeg"
-	Quality int     // 1-100, only used for JPEG
-	Scale   float64 // 0.0-1.0, 1.0 means no scaling
-	MaxSize int     // 0 means no limit
+	Format            string                   // "png" or "jpeg"
+	Quality           int                      // 1-100, only used for JPEG
+	Scale             float64                  // 0.0-1.0, 1.0 means no scaling
+	MaxSize           int                      // 0 means no limit
+	Clip              *types.ScreenElementRect // nil means no cropping
+	ScreenWidthPoints int                      // screen width in points, required when Rect is set
 }
 
 // ScreenCaptureConfig contains configuration for screen capture operations

devices/ios.go

@@ -199,7 +199,7 @@ func (d *IOSDevice) TakeScreenshot(opts ScreenshotOptions) ([]byte, error) {
 	if err != nil {
 		return nil, err
 	}
-	return utils.ProcessScreenshot(data, opts.Format, opts.Quality, opts.Scale, opts.MaxSize)
+	return utils.ProcessScreenshot(data, opts.Format, opts.Quality, opts.Scale, opts.MaxSize, opts.Clip, opts.ScreenWidthPoints)
 }
 
 func (d *IOSDevice) Reboot() error {

devices/remote.go

@@ -112,6 +112,9 @@ func (r *RemoteDevice) TakeScreenshot(opts ScreenshotOptions) ([]byte, error) {
 	if opts.MaxSize > 0 {
 		p["maxSize"] = opts.MaxSize
 	}
+	if opts.Clip != nil {
+		p["clip"] = opts.Clip
+	}
 	resp, err := rpcCall[struct {
 		Data string `json:"data"`
 	}](r, "device.screenshot", p)

devices/simulator.go

@@ -91,7 +91,7 @@ func (s SimulatorDevice) TakeScreenshot(opts ScreenshotOptions) ([]byte, error)
 	if err != nil {
 		return nil, err
 	}
-	return utils.ProcessScreenshot(data, opts.Format, opts.Quality, opts.Scale, opts.MaxSize)
+	return utils.ProcessScreenshot(data, opts.Format, opts.Quality, opts.Scale, opts.MaxSize, opts.Clip, opts.ScreenWidthPoints)
 }
 
 // Reboot shuts down and then boots the iOS simulator.