adb-scrollshot 0.1.0__py3-none-any.whl

adb_scrollshot/__init__.py

@@ -0,0 +1,6 @@
+"""Lossless Android scrolling screenshot capture and stitching."""
+
+from .api import capture_screenshot, export_pages, stitch_screenshots
+
+__version__ = "0.1.0"
+__all__ = ["__version__", "capture_screenshot", "export_pages", "stitch_screenshots"]

adb_scrollshot/__main__.py

@@ -0,0 +1,3 @@
+from .cli import entrypoint
+
+raise SystemExit(entrypoint())

adb_scrollshot/adb.py

@@ -0,0 +1,54 @@
+"""Android device discovery and lossless PNG capture."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+import cv2
+import numpy as np
+
+
+def run_adb(prefix: list[str], *args: str, timeout: int = 35) -> bytes:
+    cmd = [*prefix, *args]
+    try:
+        result = subprocess.run(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False, timeout=timeout
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError(f"ADB timed out: {' '.join(cmd)}") from exc
+    except OSError as exc:
+        raise RuntimeError(f"Unable to run adb: {exc}") from exc
+    if result.returncode != 0:
+        err = result.stderr.decode("utf-8", "replace").strip()
+        raise RuntimeError(f"ADB failed: {' '.join(cmd)}\n{err}")
+    return result.stdout
+
+
+def get_adb_prefix(serial: str | None) -> list[str]:
+    if shutil.which("adb") is None:
+        raise RuntimeError("adb is not installed. On macOS: brew install android-platform-tools")
+    raw = run_adb(["adb"], "devices").decode("utf-8", "replace")
+    entries = [row.split() for row in raw.splitlines()[1:] if row.strip()]
+    online = [parts[0] for parts in entries if len(parts) > 1 and parts[1] == "device"]
+    if serial is not None and serial not in online:
+        raise RuntimeError(f"Device {serial!r} is not connected/authorized. adb devices:\n{raw}")
+    if not online:
+        raise RuntimeError(
+            "No authorized Android device found. Check adb devices, USB debugging or wireless ADB."
+        )
+    if serial is None and len(online) != 1:
+        raise RuntimeError(
+            f"Multiple devices connected ({', '.join(online)}). Pass --serial DEVICE_ID."
+        )
+    return ["adb", "-s", serial or online[0]]
+
+
+def get_screenshot(prefix: list[str]) -> tuple[np.ndarray, bytes]:
+    data = run_adb(prefix, "exec-out", "screencap", "-p", timeout=60)
+    if not data.startswith(b"\x89PNG\r\n\x1a\n"):
+        raise RuntimeError("ADB screenshot output was not a valid PNG")
+    image = cv2.imdecode(np.frombuffer(data, dtype=np.uint8), cv2.IMREAD_COLOR)
+    if image is None:
+        raise RuntimeError("Unable to decode screenshot PNG")
+    return image, data

adb_scrollshot/api.py

@@ -0,0 +1,118 @@
+"""Public functions for lossless capture and stitching from Python."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Literal
+
+import numpy as np
+
+from .adb import get_adb_prefix, get_screenshot
+from .images import export_tiles, save_composite
+from .matching import overlapping_shift, unchanged
+from .selection import validate_roi
+
+
+def _png_path(output: str | Path) -> Path:
+    path = Path(output)
+    if path.suffix.lower() != ".png":
+        raise ValueError("Output must end in .png to preserve lossless quality")
+    return path
+
+
+def _validate_image(image: np.ndarray) -> None:
+    if (
+        not isinstance(image, np.ndarray)
+        or image.dtype != np.uint8
+        or image.ndim != 3
+        or image.shape[2] != 3
+        or min(image.shape[:2]) < 1
+    ):
+        raise ValueError("Expected a nonempty uint8 BGR image with shape (height, width, 3)")
+
+
+def capture_screenshot(
+    output: str | Path | None = None, *, serial: str | None = None
+) -> np.ndarray:
+    """Capture a native-resolution BGR image; optionally save the original PNG.
+
+    Requires ADB on PATH and an authorized, unlocked Android phone. Raises
+    RuntimeError on device errors, ValueError for invalid output, and OSError
+    for file errors. Does not scroll or change phone settings.
+    """
+    path = _png_path(output) if output is not None else None
+    image, png = get_screenshot(get_adb_prefix(serial))
+    if path is not None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(png)
+    return image
+
+
+def export_pages(image: np.ndarray, output: str | Path, *, tile_height: int = 3120) -> list[Path]:
+    """Save native-resolution sections to <output-stem>_pages/page_0001.png, etc.
+
+    The output argument names the reference PNG, not a directory. This function
+    writes only the sections. Use a fresh stem to avoid files from earlier runs.
+    """
+    path = _png_path(output)
+    _validate_image(image)
+    if tile_height < 1:
+        raise ValueError("tile_height must be positive")
+    return export_tiles(image, path, tile_height)
+
+
+def stitch_screenshots(
+    frames: Iterable[np.ndarray],
+    output: str | Path,
+    *,
+    roi: tuple[int, int, int, int] | None = None,
+    layout: Literal["continuous", "full-first"] = "continuous",
+    min_score: float = 0.80,
+) -> Path:
+    """Stitch ordered screenshots at their captured resolution and save a PNG.
+
+    Frames are uint8 BGR arrays (as returned by OpenCV), captured top-to-bottom
+    with overlapping content. ROI is (x, y, width, height) in source pixels;
+    omit it only when the entire screen scrolls. Fixed UI must be outside ROI.
+    Identical consecutive frames are ignored. This function never operates the
+    phone; use the CLI for automatic swiping and capture.
+
+    Raises ValueError for empty/invalid input or an unsafe overlap. No output
+    is written unless all input frames are accepted. Holds appended strips in
+    memory. Existing output is overwritten on success.
+    """
+    path = _png_path(output)
+    if layout not in ("continuous", "full-first"):
+        raise ValueError("layout must be continuous or full-first")
+    if not 0 < min_score <= 1:
+        raise ValueError("min_score must be in (0, 1]")
+    iterator = iter(frames)
+    try:
+        first = next(iterator)
+    except StopIteration as exc:
+        raise ValueError("At least one screenshot is required") from exc
+    _validate_image(first)
+    first = first.copy()
+    height, width = first.shape[:2]
+    rect = validate_roi(first, roi if roi is not None else (0, 0, width, height))
+    x, y, w, h = rect
+    previous = first[y : y + h, x : x + w].copy()
+    strips = []
+    for index, frame in enumerate(iterator, start=2):
+        _validate_image(frame)
+        if frame.shape != first.shape:
+            raise ValueError(f"Screenshot {index} has a different size or orientation")
+        current = frame[y : y + h, x : x + w]
+        if unchanged(previous, current):
+            continue
+        match = overlapping_shift(previous, current, min_score=min_score)
+        if match is None:
+            raise ValueError(f"Cannot safely match overlap for screenshot {index}")
+        shift = match[0]
+        extra = first[y + h - shift : y + h].copy()
+        extra[:, x : x + w] = current[h - shift : h]
+        strips.append(extra)
+        previous = current.copy()
+    save_composite(first, rect, strips, path, layout)
+    return path

adb_scrollshot/cli.py

@@ -0,0 +1,273 @@
+"""Capture lossless Android scrolling screenshots with automatic overlap removal.
+
+Start with the phone unlocked at the top of a page. Select only the scrolling
+viewport, excluding fixed headers and footers. Outputs retain captured pixels.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from . import __version__
+from .adb import get_adb_prefix, get_screenshot, run_adb
+from .images import export_tiles, save_composite
+from .matching import overlapping_shift, unchanged
+from .selection import choose_roi, validate_roi
+
+
+def parse_roi(value: str) -> tuple[int, int, int, int]:
+    try:
+        values = tuple(int(v.strip()) for v in value.split(","))
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("Use --roi x,y,width,height") from exc
+    if len(values) != 4 or any(v < 0 for v in values[:2]) or min(values[2:]) <= 0:
+        raise argparse.ArgumentTypeError("Use --roi x,y,width,height with positive dimensions")
+    return values
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    choose = p.add_mutually_exclusive_group()
+    choose.add_argument(
+        "--select",
+        action="store_true",
+        help="Draw a rectangle around the scrollable part (default)",
+    )
+    choose.add_argument(
+        "--roi", type=parse_roi, help="Scrollable rectangle in phone pixels: x,y,width,height"
+    )
+    choose.add_argument(
+        "--whole-screen", action="store_true", help="Treat full phone screen as scrollable"
+    )
+    p.add_argument("--output", type=Path, default=Path("captures/long_screenshot.png"))
+    p.add_argument(
+        "--tile-height",
+        type=int,
+        default=0,
+        help="Also export full-resolution PNG pages of this height (e.g. 3120); 0 disables",
+    )
+    p.add_argument(
+        "--layout",
+        choices=["continuous", "full-first"],
+        default="continuous",
+        help="continuous: footer only at bottom; full-first: exact original screenshot at top",
+    )
+    p.add_argument("--serial", help="ADB device serial (required with multiple connected devices)")
+    p.add_argument("--max-swipes", type=int, default=45, help="Safety cap (default 45)")
+    p.add_argument(
+        "--swipe-duration", type=int, default=650, help="Swipe length in milliseconds (default 650)"
+    )
+    p.add_argument(
+        "--pause", type=float, default=0.85, help="Seconds to wait after each swipe (default 0.85)"
+    )
+    p.add_argument(
+        "--swipe-x", type=int, help="Override swipe horizontal coordinate in device pixels"
+    )
+    p.add_argument(
+        "--stop-after",
+        type=int,
+        default=2,
+        help="Consecutive unchanged screenshots to stop (default 2)",
+    )
+    p.add_argument(
+        "--keep-frames", action="store_true", help="Save every lossless PNG in a *_frames folder"
+    )
+    p.add_argument(
+        "--preview-height", type=int, default=760, help="Selection preview max height (default 760)"
+    )
+    p.add_argument(
+        "--min-score", type=float, default=0.80, help="Match confidence 0..1 (default .80)"
+    )
+    args = p.parse_args(argv)
+    if args.output.suffix.lower() != ".png":
+        p.error("--output must end in .png to preserve lossless screenshot quality")
+    if args.tile_height < 0:
+        p.error("--tile-height must be 0 or a positive number of pixels")
+    if (
+        args.max_swipes < 1
+        or args.stop_after < 1
+        or args.swipe_duration < 100
+        or args.pause < 0
+        or args.preview_height < 200
+    ):
+        p.error(
+            "Invalid value for max-swipes, stop-after, swipe-duration, pause, or preview-height"
+        )
+    if not 0 < args.min_score <= 1:
+        p.error("--min-score must be in (0, 1]")
+
+    prefix = get_adb_prefix(args.serial)
+    print(f"Connected to {prefix[-1]}. Keep the desired page open at its TOP.", flush=True)
+    first, png = get_screenshot(prefix)
+    screen_h, screen_w = first.shape[:2]
+    print(f"Native screenshot: {screen_w} x {screen_h} pixels (lossless PNG).", flush=True)
+    if args.whole_screen:
+        rect = (0, 0, screen_w, screen_h)
+    elif args.roi:
+        rect = args.roi
+    else:
+        rect = choose_roi(first, args.preview_height)
+    rect = validate_roi(first, rect)
+    x, y, w, h = rect
+    print(f"Chosen scrolling region: x={x}, y={y}, width={w}, height={h}", flush=True)
+
+    # Swipes are directed *inside* the scrollable viewport, so fixed toolbars
+    # outside the selected region are never touched.
+    sx = args.swipe_x if args.swipe_x is not None else x + w // 2
+    sy1 = y + int(h * 0.77)
+    sy2 = y + int(h * 0.30)
+    if not 0 <= sx < screen_w or sy2 < 0 or sy1 >= screen_h or sy1 - sy2 < 80:
+        p.error("Computed swipe coordinates invalid. Check ROI / --swipe-x")
+    print(f"Auto swipe: ({sx}, {sy1}) -> ({sx}, {sy2}) for {args.swipe_duration} ms", flush=True)
+
+    frame_dir = args.output.parent / f"{args.output.stem}_frames"
+    if args.keep_frames:
+        frame_dir.mkdir(parents=True, exist_ok=True)
+        (frame_dir / "0000.png").write_bytes(png)
+
+    previous = first[y : y + h, x : x + w].copy()
+    strips: list[np.ndarray] = []
+    stable_count = 0
+    completed = False
+    stopped_for_error = False
+    accepted = 0
+    total_scrolled = 0
+    print(
+        "Capturing and stitching automatically. Press Ctrl+C to stop and save progress.\n",
+        flush=True,
+    )
+    try:
+        for step in range(1, args.max_swipes + 1):
+            run_adb(
+                prefix,
+                "shell",
+                "input",
+                "swipe",
+                str(sx),
+                str(sy1),
+                str(sx),
+                str(sy2),
+                str(args.swipe_duration),
+            )
+            time.sleep(args.pause)
+            new, raw = get_screenshot(prefix)
+            if new.shape != first.shape:
+                print(
+                    "Display resolution/orientation changed. Stopping to avoid corrupt image.",
+                    file=sys.stderr,
+                )
+                stopped_for_error = True
+                break
+            if args.keep_frames:
+                (frame_dir / f"{step:04d}.png").write_bytes(raw)
+            current = new[y : y + h, x : x + w]
+            if unchanged(previous, current):
+                stable_count += 1
+                print(
+                    f"  Swipe {step:02}: no movement ({stable_count}/{args.stop_after}).",
+                    flush=True,
+                )
+                if stable_count >= args.stop_after:
+                    completed = True
+                    break
+                continue
+            stable_count = 0
+            matched = overlapping_shift(previous, current, min_score=args.min_score)
+            if matched is None:
+                # If screenshots were taken during animation, a delayed capture
+                # can fix them. Do not swipe again before resolving this match.
+                print(
+                    f"  Swipe {step:02}: overlap unclear; retrying screenshot after settling...",
+                    flush=True,
+                )
+                time.sleep(max(0.8, args.pause))
+                settled, settled_png = get_screenshot(prefix)
+                if settled.shape == first.shape:
+                    new, raw = settled, settled_png
+                    current = new[y : y + h, x : x + w]
+                    if args.keep_frames:
+                        (frame_dir / f"{step:04d}.png").write_bytes(raw)
+                    if unchanged(previous, current):
+                        stable_count = 1
+                        print("  No visible movement after settling.", flush=True)
+                        continue
+                    matched = overlapping_shift(previous, current, min_score=args.min_score)
+            if matched is None:
+                print(
+                    "  STOP: could not safely match new content to earlier screenshot.",
+                    file=sys.stderr,
+                )
+                print(
+                    "  The partial image will be saved. Try a tighter ROI, slower swipes,",
+                    file=sys.stderr,
+                )
+                print("  or a longer --swipe-duration / --pause.", file=sys.stderr)
+                stopped_for_error = True
+                break
+            shift, conf, error = matched
+            # Append exactly the freshly revealed strip from the LOSSLESS PNG.
+            # Any side margin outside the selected ROI comes from the first
+            # screenshot (like the original video-based partial stitcher).
+            extra = first[y + h - shift : y + h].copy()
+            extra[:, x : x + w] = current[h - shift : h]
+            strips.append(extra)
+            accepted += 1
+            total_scrolled += shift
+            previous = current.copy()
+            print(
+                f"  Swipe {step:02}: +{shift} px | match {conf:.3f} | error {error:.2f}", flush=True
+            )
+        else:
+            print(
+                f"Maximum of {args.max_swipes} swipes reached; output may be incomplete.",
+                file=sys.stderr,
+            )
+    except (RuntimeError, OSError) as exc:
+        print(f"Capture stopped: {exc}. Saving captured content.", file=sys.stderr)
+        stopped_for_error = True
+    except KeyboardInterrupt:
+        print("\nInterrupted. Saving the captured content.", flush=True)
+
+    out_w, out_h = save_composite(first, rect, strips, args.output, args.layout)
+    print(f"\nSaved: {args.output.resolve()}", flush=True)
+    print(
+        f"Resolution: {out_w} x {out_h} pixels; {accepted} matched swipes; {total_scrolled} added rows.",
+        flush=True,
+    )
+    print("View at 100% / Actual Size to inspect detail. Fit-to-window shrinks long images.")
+    if args.tile_height:
+        composite = cv2.imread(str(args.output), cv2.IMREAD_COLOR)
+        if composite is None:
+            raise RuntimeError(f"Could not read saved PNG: {args.output}")
+        pages = export_tiles(composite, args.output, args.tile_height)
+        print(f"Also saved {len(pages)} full-resolution PNG pages: {pages[0].parent.resolve()}")
+    if args.keep_frames:
+        print(f"Original PNGs: {frame_dir.resolve()}", flush=True)
+    if args.layout == "full-first" and y + h < screen_h and accepted:
+        print("Note: full-first places the original bottom bar before the appended content.")
+    if completed:
+        print("End detected: scrolling stopped changing the selected area.", flush=True)
+    if stopped_for_error:
+        print(
+            "Partial result saved; stitching stopped because matching was unreliable.", flush=True
+        )
+        return 2
+    return 0
+
+
+def entrypoint() -> int:
+    """Present actionable errors without an internal traceback."""
+    try:
+        return main()
+    except (RuntimeError, ValueError, OSError, cv2.error) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1

adb_scrollshot/images.py

@@ -0,0 +1,46 @@
+"""Compose and export native-resolution PNG images."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+
+def save_composite(
+    first: np.ndarray,
+    rect: tuple[int, int, int, int],
+    additions: list[np.ndarray],
+    output: Path,
+    layout: str,
+) -> tuple[int, int]:
+    x, y, rw, rh = rect
+    parts: list[np.ndarray] = [first.copy() if layout == "full-first" else first[: y + rh].copy()]
+    parts.extend(additions)
+    if layout == "continuous" and y + rh < first.shape[0]:
+        parts.append(first[y + rh :].copy())
+    height = sum(part.shape[0] for part in parts)
+    width = first.shape[1]
+    if height > 2**31 - 1:
+        raise RuntimeError("Image height exceeds supported limits; decrease --max-swipes")
+    composite = np.concatenate(parts, axis=0)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    if not cv2.imwrite(str(output), composite, [cv2.IMWRITE_PNG_COMPRESSION, 6]):
+        raise RuntimeError(f"Could not save PNG to {output}")
+    return width, height
+
+
+def export_tiles(image: np.ndarray, output: Path, tile_height: int) -> list[Path]:
+    """Split into native-resolution PNGs without resampling or losing any rows."""
+    folder = output.parent / f"{output.stem}_pages"
+    folder.mkdir(parents=True, exist_ok=True)
+    paths = []
+    for index, top in enumerate(range(0, image.shape[0], tile_height), start=1):
+        path = folder / f"page_{index:04d}.png"
+        if not cv2.imwrite(
+            str(path), image[top : top + tile_height], [cv2.IMWRITE_PNG_COMPRESSION, 6]
+        ):
+            raise RuntimeError(f"Could not save PNG to {path}")
+        paths.append(path)
+    return paths

adb_scrollshot/matching.py

@@ -0,0 +1,91 @@
+"""Detect vertical overlap without scaling the saved pixels."""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+
+def small_gray(image: np.ndarray) -> tuple[np.ndarray, float]:
+    h, w = image.shape[:2]
+    scale = min(1.0, 540 / w, 1250 / h)
+    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+    if scale < 1:
+        gray = cv2.resize(
+            gray, (max(1, round(w * scale)), max(1, round(h * scale))), interpolation=cv2.INTER_AREA
+        )
+    # Return actual y scaling, not ideal scaling after rounding dimensions.
+    return gray, gray.shape[0] / h
+
+
+def unchanged(old: np.ndarray, new: np.ndarray) -> bool:
+    """Check for end of scrolling, tolerating a small animation / indicator."""
+    a, _ = small_gray(old)
+    b, _ = small_gray(new)
+    if a.shape != b.shape:
+        return False
+    # Ignore a little of the sides (scrollbars/selection highlights).
+    w = a.shape[1]
+    x0, x1 = int(w * 0.08), max(int(w * 0.92), int(w * 0.08) + 1)
+    diff = cv2.absdiff(a[:, x0:x1], b[:, x0:x1])
+    return float(np.mean(diff)) < 1.0 and float(np.mean(diff > 12)) < 0.008
+
+
+def overlapping_shift(
+    old: np.ndarray,
+    new: np.ndarray,
+    min_scroll: int = 8,
+    min_score: float = 0.80,
+    max_error: float = 17.0,
+) -> tuple[int, float, float] | None:
+    """Find upward movement by exact-resolution row alignment.
+
+    Shrinks ONLY the horizontal sampling density for faster template matching;
+    vertical positions are never scaled, to avoid misaligning repeated chat
+    messages, lines, or lists by one or more line heights.
+    """
+    h, w = old.shape[:2]
+    if old.shape != new.shape:
+        return None
+    left = int(0.12 * w)
+    right = max(left + 1, int(0.88 * w))
+    # ADB captures native-res PNGs. Avoid vertically resizing pixel positions.
+    stride_x = max(1, (right - left) // 190)
+    oa = cv2.cvtColor(old, cv2.COLOR_BGR2GRAY)[:, left:right:stride_x]
+    nb = cv2.cvtColor(new, cv2.COLOR_BGR2GRAY)[:, left:right:stride_x]
+    max_shift = int(0.80 * h)
+    candidate_scores: dict[int, float] = {}
+    for rel_y in (0.055, 0.14, 0.27, 0.38):
+        anchor = int(h * rel_y)
+        th = min(max(35, int(0.14 * h)), h - anchor - 3)
+        if th < 20:
+            continue
+        templ = nb[anchor : anchor + th]
+        if float(np.std(templ)) < 8:
+            continue
+        scores = cv2.matchTemplate(oa, templ, cv2.TM_CCOEFF_NORMED)[:, 0]
+        local = cv2.dilate(scores.reshape(-1, 1), np.ones((9, 1), np.uint8))[:, 0]
+        peaks = np.where((scores >= min_score) & (scores >= local - 1e-6))[0]
+        peaks = sorted(peaks, key=lambda iy: float(scores[iy]), reverse=True)[:10]
+        for loc_y in peaks:
+            shift = int(loc_y) - anchor
+            if min_scroll <= shift <= max_shift:
+                candidate_scores[shift] = max(
+                    candidate_scores.get(shift, 0.0), float(scores[loc_y])
+                )
+    if not candidate_scores:
+        return None
+
+    # Compare all feature-containing rows, in the native vertical pixel grid.
+    # One correct alignment should have nearly identical pixel values, even
+    # when different rows contain repeated UI patterns.
+    trials: list[tuple[float, float, int]] = []
+    for shift, score in candidate_scores.items():
+        # Robust to a small amount of live text, clocks, cursor blinking, etc.
+        diff = cv2.absdiff(oa[shift:], nb[: h - shift])
+        error = float(np.mean(diff))
+        trials.append((error, -score, shift))
+    error, neg_score, shift = min(trials)
+    if error > max_error:
+        return None
+    return shift, -neg_score, error

adb_scrollshot/selection.py

@@ -0,0 +1,44 @@
+"""Select and validate the scrolling viewport."""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+
+def choose_roi(first: np.ndarray, preview_height: int) -> tuple[int, int, int, int]:
+    height, width = first.shape[:2]
+    scale = min(1.0, preview_height / height, 1000.0 / width)
+    preview = (
+        cv2.resize(
+            first,
+            (max(1, round(width * scale)), max(1, round(height * scale))),
+            interpolation=cv2.INTER_AREA,
+        )
+        if scale < 1
+        else first
+    )
+    caption = "Select ONLY scrolling area, ENTER to accept, ESC to cancel"
+    try:
+        selected = cv2.selectROI(caption, preview, showCrosshair=True, fromCenter=False)
+        cv2.destroyAllWindows()
+    except cv2.error as exc:
+        raise RuntimeError(
+            f"Cannot open selection window ({exc}). Use --roi x,y,width,height instead."
+        ) from exc
+    sx, sy, sw, sh = map(int, selected)
+    if sw <= 0 or sh <= 0:
+        raise RuntimeError("No scrolling area selected. Please retry.")
+    x = max(0, round(sx / scale))
+    y = max(0, round(sy / scale))
+    w = min(width - x, round(sw / scale))
+    h = min(height - y, round(sh / scale))
+    return x, y, w, h
+
+
+def validate_roi(image: np.ndarray, rect: tuple[int, int, int, int]) -> tuple[int, int, int, int]:
+    h, w = image.shape[:2]
+    x, y, rw, rh = rect
+    if x < 0 or y < 0 or rw < 80 or rh < 160 or x + rw > w or y + rh > h:
+        raise ValueError(f"Invalid ROI {rect}; screen is {w}x{h}. Use at least 80x160.")
+    return rect

adb_scrollshot-0.1.0.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: adb-scrollshot
+Version: 0.1.0
+Summary: Lossless Android scrolling screenshots with automatic capture and overlap removal
+Project-URL: Repository, https://github.com/vishalnagda1/adb-scrollshot
+Project-URL: Documentation, https://github.com/vishalnagda1/adb-scrollshot/blob/main/README.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adb,android,image-stitching,screenshot,scrolling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
+Requires-Python: >=3.11
+Requires-Dist: numpy<3,>=2
+Requires-Dist: opencv-python<6,>=4.10
+Description-Content-Type: text/markdown
+
+# ADB Scrollshot
+
+Capture a sharp, continuous scrolling screenshot from an Android phone. The
+command automatically swipes, captures lossless PNG screenshots, removes
+matching overlap, and stops when the selected content stops moving.
+
+The final image keeps the original captured pixel resolution. Optional shorter
+PNG pages make long captures easier to view and share.
+
+## Requirements
+
+- Python 3.11 or newer and [uv](https://docs.astral.sh/uv/).
+- Android Platform Tools (`adb`) on your PATH.
+- An unlocked Android phone with USB debugging enabled and this computer authorized.
+- A desktop session for interactive area selection; use `--roi` otherwise.
+
+On macOS, install ADB with `brew install android-platform-tools`. On other
+platforms, install Android Platform Tools and add it to PATH. Confirm that
+`adb devices` lists your phone with the state `device`, not `unauthorized`.
+`adb` is a separate system prerequisite and is not included in this package.
+
+## Install from PyPI
+
+```sh
+python -m pip install adb-scrollshot
+adb-scrollshot --select --keep-frames --tile-height 3120 --output captures/high_quality.png
+```
+
+For an isolated command-line installation, use `uv tool install adb-scrollshot`.
+For Python programs, install into your project's virtual environment and import
+`adb_scrollshot`. Python 3.11 or newer is required.
+
+## Quick start
+
+From this project directory:
+
+```sh
+uv sync --locked
+uv run adb-scrollshot --select --keep-frames --tile-height 3120 --output captures/high_quality.png
+```
+
+1. Open the desired page on your phone and return to its top.
+2. Run the command. Draw a rectangle around **only the scrolling content**,
+   excluding fixed toolbars, status bars, navigation bars, and sticky headers.
+3. Press **Enter**. Leave the phone untouched while it scrolls and captures.
+4. Find `captures/high_quality.png`, its original screenshots in
+   `captures/high_quality_frames/`, and shorter PNGs in `captures/high_quality_pages/`.
+
+`scrcpy` is optional; it can mirror the phone while ADB captures directly.
+Without `--output`, the destination is `captures/long_screenshot.png`.
+Use a fresh output name for each run; existing output files may be overwritten.
+Use a fresh name especially with frame/page export to avoid leftover files
+from a previous, longer capture.
+
+The original launcher still works:
+
+```sh
+uv run python adb_scrollshot.py --select --keep-frames --tile-height 3120
+```
+
+You can also use `uv run python -m adb_scrollshot --help`.
+
+## Common options
+
+Run `uv run adb-scrollshot --help` for all options.
+
+| Option | Purpose |
+| --- | --- |
+| `--select` | Draw the scrolling area; this is the default selection mode. |
+| `--roi 0,250,1440,2500` | Specify x, y, width, height in source screenshot pixels. |
+| `--whole-screen` | Use only if the entire screen scrolls without fixed UI. |
+| `--serial DEVICE_ID` | Choose one device when several are connected. |
+| `--keep-frames` | Keep original PNGs for inspection or troubleshooting. |
+| `--tile-height 3120` | Also export native-resolution sections, at most 3120 pixels tall. |
+| `--pause 1.5` | Wait longer for rendering after each swipe. |
+| `--swipe-duration 900` | Make the upward swipe slower, in milliseconds. |
+| `--max-swipes 80` | Raise the safety limit; the default is 45. |
+| `--layout full-first` | Preserve the entire initial screen, including its footer, before appended content. |
+
+The default `continuous` layout places the initial fixed header at the top and
+its fixed footer at the end. When the selected region is narrower than the
+screen, appended side margins are copied from the first screenshot; select the
+full content width to avoid repeating unrelated side content.
+
+## Quality and limits
+
+View the PNG at **Actual Size / 100%** in your image viewer. Fitting a very tall
+image into a window can make sharp text appear blurry. Some messaging apps
+also shrink images; send the PNG as a file or share the shorter pages.
+
+The area-selection preview is reduced for convenience, but the saved content
+is not resized. PNG compression is lossless. Upscaling or recording at a higher
+video bitrate cannot add detail missing from the source screenshots.
+
+Overlap matching assumes vertically translating, static content. Animations,
+video, sticky elements inside the selection, repeated patterns, or app layout
+changes can prevent reliable matching. The tool stops and saves a partial PNG
+when it cannot match safely. Page boundaries may cut through a line of text;
+the continuous PNG remains available. Very long captures consume memory.
+
+- **Ctrl+C:** saves progress captured so far.
+- **Connection loss during scrolling:** attempts to save progress and exits with code 2.
+- **Exit 0:** normal end, user interruption, or swipe limit reached; read the
+  terminal message to see whether the bottom was actually detected.
+- **Exit 1:** setup or output error; **exit 2:** invalid arguments or a partial
+  capture caused by unreliable matching, display changes, or connection failure.
+
+No image is uploaded by this application. Captures can contain private screen
+content; they and recordings are excluded from Git and release archives.
+
+## Development
+
+```sh
+uv sync --locked
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv build
+uv run python scripts/package_release.py
+```
+
+The lockfile pins dependencies. CI checks Python 3.11 and 3.14 on Linux and builds
+artifacts. The automated tests use synthetic screenshots and simulated ADB;
+physical-device behavior still needs a manual smoke test.
+
+```text
+src/adb_scrollshot/
+  adb.py          Device discovery, commands, and lossless screen capture
+  cli.py          Argument parsing and automatic capture loop
+  images.py       PNG composition and page export
+  matching.py     Overlap matching and end detection
+  selection.py    Interactive region selection and validation
+  __main__.py     Python module entry point
+tests/            Device-free regression tests
+scripts/          Source-delivery ZIP builder
+docs/             Delivery, installation, and manual validation guide
+.github/workflows/ci.yml
+```
+
+See [docs/DELIVERY.md](docs/DELIVERY.md) for installation from a wheel, release
+contents, a manual acceptance checklist, and Git handoff commands.
+
+## Use as a Python library
+
+Install with `python -m pip install adb-scrollshot` and import `adb_scrollshot`.
+You can also install the supplied wheel with
+`python -m pip install ./dist/adb_scrollshot-0.1.0-py3-none-any.whl`, or run these
+examples inside this checkout with `uv run python`.
+
+Capture a single lossless screen, without scrolling:
+
+```python
+from adb_scrollshot import capture_screenshot
+
+image = capture_screenshot("captures/screen.png")
+print(image.shape)  # (height, width, 3), uint8 BGR pixels
+```
+
+Stitch screenshots captured in top-to-bottom order (each must overlap the last):
+
+```python
+import cv2
+from adb_scrollshot import export_pages, stitch_screenshots
+
+frames = [cv2.imread(path) for path in ["screen1.png", "screen2.png", "screen3.png"]]
+output = stitch_screenshots(
+    frames,
+    "captures/stitched.png",
+    roi=(0, 250, 1440, 2500),  # adapt to your screenshots; exclude fixed UI
+)
+pages = export_pages(cv2.imread(str(output)), output, tile_height=3120)
+```
+
+`stitch_screenshots` accepts an iterable of OpenCV BGR arrays, skips unchanged
+captures, and raises `ValueError` on invalid input or unreliable overlap. It
+writes only after all frames have been accepted. `capture_screenshot` raises
+`RuntimeError` for ADB errors; filesystem errors propagate as `OSError`.
+For automatic scrolling, use the `adb-scrollshot` CLI. ADB is required for live
+capture, but not for stitching existing frames or exporting pages.
+
+Public PyPI publishing is configured separately. See
+[docs/PUBLISHING.md](docs/PUBLISHING.md) for the one-time account setup and release procedure.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

adb_scrollshot-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+adb_scrollshot/__init__.py,sha256=E5B9VLXs38hlx9fwTcEHtkWCxfC-qUa3BgbmSdD8cNQ,247
+adb_scrollshot/__main__.py,sha256=PIJIOolexzGnrOJz3yXWQZ6eCKD9h2LLAao-qtQ8HYE,60
+adb_scrollshot/adb.py,sha256=RFNa0K_PmkT2VC0aNutgwG1P7OR-lURUtANw0SCZeN0,2187
+adb_scrollshot/api.py,sha256=SfPOWTRWdAYb9xygQ7qqplLDpEEJhs9p8moHJZ8M5kQ,4488
+adb_scrollshot/cli.py,sha256=jkrxuFByXdOu7OTlLilcKO1hCyp_s_HhObIWevrDYIk,11157
+adb_scrollshot/images.py,sha256=B1FGJ7RGBUAkY5zy0334RuvjSxpPW6nkSeyJwFtb4AU,1683
+adb_scrollshot/matching.py,sha256=2BVxfpnEJxRSlrd3NSxJWa5j6IM5iFpJZSfPgcOhzac,3606
+adb_scrollshot/selection.py,sha256=L9-GvvMN-pyWTpkgpE_SRMBBEFGHMgCj0LwrLnEiD2c,1545
+adb_scrollshot-0.1.0.dist-info/METADATA,sha256=vC1Qu76dreCFL_nHs-1cqJQS0hWO2o2YOpjH-ZekEjs,8635
+adb_scrollshot-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+adb_scrollshot-0.1.0.dist-info/entry_points.txt,sha256=yB8ix9n1mf_VeuTpAmWVSIRbqOLxbXrWjVK0kak4lmQ,65
+adb_scrollshot-0.1.0.dist-info/licenses/LICENSE,sha256=z7wQoYD3QaQdUt1NBQdiEgtvYDgdNFOEBqm-HzB3rDQ,1069
+adb_scrollshot-0.1.0.dist-info/RECORD,,

adb_scrollshot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

adb_scrollshot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+adb-scrollshot = adb_scrollshot.cli:entrypoint

adb_scrollshot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vishal Nagda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.