CAPTUREFLOW 1.0.0 Screenshot to Documentation - Pro variant Techlosoft desktop tools (Windows and macOS) ================================================================================ WHAT IT IS captureflow is a desktop command-line tool that EDITS THE PIXELS of screenshots. It draws boxes and arrows, pixelates regions with a real block average, and blacks regions out - and it does that to a whole folder of images in one command, using one shared region file. That last part is the point. A click-by-click GUI editor cannot redact forty support screenshots identically. captureflow can, because the coordinates live in a file instead of in your mouse. Sibling tool: SnapDocs assembles the annotated images into a document. captureflow is the pixel editor that runs before it. This is a native desktop CLI. There is no web version and no browser build. -------------------------------------------------------------------------------- INSTALL Copy the binary for your platform out of dist/ and put it on your PATH. dist/captureflow-windows-amd64.exe Windows 10/11, 64-bit dist/captureflow-darwin-arm64 macOS on Apple Silicon dist/captureflow-darwin-amd64 macOS on Intel dist/captureflow-linux-amd64 Linux, 64-bit (build/CI convenience) No installer, no runtime, no dependencies. One static executable. Building from source needs only a Go 1.24 toolchain: go build -o captureflow . The tool uses the Go standard library exclusively (image, image/png, image/jpeg, image/draw and friends). There are no third-party modules, so `GOPROXY=off go build` works on a machine with no network access. -------------------------------------------------------------------------------- COMMANDS captureflow annotate --out [ops...] captureflow redact --out --regions [--apply] captureflow inspect [--json] captureflow help -h, --help and help all print this usage and exit 0. A bad invocation prints the usage to stderr and exits 1. ANNOTATE Applies drawing operations to ONE image and writes the result to --out. The operations are applied IN THE ORDER YOU TYPE THEM, left to right, so a box typed after a pixelate is drawn on top of the pixelated area, and a pixelate typed after a box averages the box away. --box X,Y,W,H[,COLOR][,WIDTH] Rectangle OUTLINE. The border of thickness WIDTH is drawn INSIDE the rectangle, so the annotation never spills past the coordinates given. Defaults: COLOR red, WIDTH 3. --arrow X1,Y1,X2,Y2[,COLOR][,WIDTH] A line of thickness WIDTH from (X1,Y1) to (X2,Y2) with a filled triangular arrowhead whose tip is exactly at (X2,Y2). The head is 4*WIDTH long and 4*WIDTH wide at its base. The shaft has a ROUND cap, so it extends about WIDTH/2 pixels past (X1,Y1). Defaults: COLOR red, WIDTH 3. --pixelate X,Y,W,H[,BLOCK] Real block-average pixelation - see PIXELATION below. Default BLOCK 8. --blackout X,Y,W,H[,COLOR] Solid fill. Every pixel in the region becomes exactly COLOR. Default COLOR black. Each op may be repeated as many times as you like. --out REQUIRED. Must not be the input file. --quality JPEG output quality, 1-100, default 92. Ignored for PNG. REDACT Applies one named region set to EVERY PNG and JPEG in a folder, writing the redacted copies into --out under the same file names. This is the Pro feature. captureflow redact ./tickets --out ./clean --regions redact.json (dry run) captureflow redact ./tickets --out ./clean --regions redact.json --apply (writes) It is a DRY RUN by default: without --apply, nothing is written at all, not even the output directory. The dry run still decodes every image and resolves every region, so it fails loudly on a bad region file before touching disk. Only the named folder is scanned; subdirectories are not descended into. Files are processed in sorted order. Non-image files are ignored. Region file format: { "regions": [ {"name": "customer-email", "type": "pixelate", "rect": "0,10%,100%,20%", "block": 10}, {"name": "licence-key", "type": "blackout", "rect": "10%,50%,30%,10%", "color": "black"}, {"name": "focus", "type": "box", "rect": "2%,2%,96%,96%", "color": "yellow", "width": 4}, {"name": "pointer", "type": "arrow", "rect": "10,10,120,90", "color": "red", "width": 3} ] } name Free text, used in the printed plan and in error messages. Optional. type pixelate (the default if omitted), blackout, box or arrow. rect The coordinate string, same syntax as the command-line ops. For an arrow it is X1,Y1,X2,Y2 rather than X,Y,W,H. block pixelate only. color / width box, arrow and blackout only. Regions are applied to every image in the order they appear in the file. INSPECT Prints dimensions, format, colour model, opacity and file size - what you need to work out coordinates. --json emits the same data as a JSON object with the keys tool, version, file, format, width, height, pixels, color_model, opaque, bytes and human_size. -------------------------------------------------------------------------------- COORDINATES: PIXELS OR PERCENTAGES X,Y is the top-left pixel of the region; W,H are its width and height. The region covers x = X .. X+W-1 and y = Y .. Y+H-1. ANY of the four numbers may instead be a PERCENTAGE, written with a trailing per-cent sign: 10%, 33.5%, 100%. X and W are percentages of the image WIDTH, Y and H percentages of the image HEIGHT. The result is rounded to the nearest whole pixel. Percentages and pixels may be mixed inside one region: 0,10%,100%,20% a full-width band from 10% to 30% down the image 10%,50%,30%,10% a box in the left-middle, sized relative to the image 40,60,200,80 plain pixels This is what lets ONE region file redact screenshots of different sizes - a 400x300 ticket and an 800x600 ticket get the same region in the same relative place. CLAMPING AND ERRORS - A region that hangs off the edge is CLAMPED to the image, and the clamp is reported in the run log, e.g. "(clamped from 350,270,200x200)". - Negative X or Y are clamped to 0 the same way. - A region entirely outside the image is an ERROR (exit 1), because it almost always means the coordinates are wrong rather than merely generous. - Zero or negative W or H is an ERROR (exit 1). - Arrows are simply clipped to the canvas; off-canvas endpoints are allowed, which is how you draw an arrow that enters from outside the frame. COLOURS #rrggbb, or one of: red, green, blue, black, white, yellow, orange, cyan, magenta, gray. Names are case-insensitive. All colours are fully opaque. -------------------------------------------------------------------------------- PIXELATION - WHAT IT ACTUALLY DOES This is a real pixelation, not a blur and not a grey rectangle. The region is divided into a grid of BLOCK x BLOCK cells anchored at the region's top-left corner. For each cell captureflow reads the original pixels, computes the ARITHMETIC MEAN of each channel over that cell, and writes that single averaged value back to every pixel in the cell. - Channel means use integer floor division: sum of channel / pixel count. So a cell whose red values sum to 12 345 over 100 pixels becomes red 123, not 123.45 rounded to 123. This is deterministic and reproducible. - Cells clipped by the region edge (when BLOCK does not divide W or H, or when the region was clamped) are averaged over only the pixels they actually cover. A 4x7 edge cell averages 28 pixels, not 49. - Nothing outside the region is touched, not one pixel. - A BLOCK larger than the region collapses the whole region to a single average colour. That is legitimate and is not an error. Because the output is the mean of the original, the underlying detail is gone for good - it cannot be recovered by sharpening the output image. SECURITY NOTE. Pixelation is a visual redaction. For text that MUST be unrecoverable, use --blackout, which replaces the region with a single flat colour and preserves no statistical trace of what was underneath. Small pixelation blocks over short text can in principle be attacked; a blackout cannot. When in doubt, black it out. -------------------------------------------------------------------------------- SAFETY - The source image is NEVER modified. annotate refuses to run if --out resolves to the input file. redact refuses if --out is the input directory. - redact is a dry run unless --apply is passed. - If encoding the output fails part-way, the partial file is removed rather than left behind as a corrupt image. - Bad input - a non-image, a truncated PNG, an empty file, an unparseable region string, an unknown colour, a malformed region file - produces a single clear message on stderr and exit status 1. No stack traces, no half-written outputs. -------------------------------------------------------------------------------- WHAT IS IMPLEMENTED - annotate with --box, --arrow, --pixelate and --blackout, repeatable and applied strictly in command-line order. - Real block-average pixelation, including partial edge cells. - Blackout with an exact solid fill. - Box outlines with configurable colour and border width, drawn inside the given rectangle. - Arrows with a filled triangular head, any angle, endpoints allowed off canvas. - Coordinates in pixels OR percentages, mixable within a region. - Batch redact over a folder from a JSON region set, with dry run by default. - inspect, with a --json form. - PNG input and output (lossless), JPEG input and output (lossy, quality configurable), and conversion between the two in either direction. - Region clamping to image bounds with the clamp reported. - Static single-file binaries for Windows, macOS (Intel and Apple Silicon) and Linux. WHAT IS NOT IMPLEMENTED - THERE IS NO INTERACTIVE GUI REGION PICKER. You do not draw a box with the mouse. Coordinates are supplied on the command line or in a region file. That is a deliberate design decision, not an omission: it is precisely what makes batch redaction possible. A region set is text, so it can be reused across forty screenshots, committed to a repository, reviewed in a pull request, and re-run when the screenshots are retaken. A mouse cannot do any of that. - No OCR. captureflow does not find text; it cannot decide for you where the email addresses are. You tell it where to redact. - No screen capture. captureflow edits images that already exist on disk. Use your operating system's capture tool (or SnapDocs) to produce them. - No text, callout labels, numbered step badges or speech bubbles. Boxes, arrows, pixelation and fills only. - No blur, drop shadow, rounded corner, gradient or opacity/alpha blending. Every drawing operation writes fully opaque pixels. - No GIF, WebP, BMP, TIFF, HEIC or SVG. PNG and JPEG only, both directions. - No recursive folder walking in redact; only the named directory is scanned. - No undo journal. Outputs go to a separate destination, so undo is simply deleting the output. - No animation, video or multi-frame input. - No cropping, resizing, rotation or colour correction. -------------------------------------------------------------------------------- ROADMAP 1. Interactive region picker. A small native window that opens a screenshot, lets you drag out regions with the mouse, and EMITS A REGION FILE - the coordinates then feed straight back into batch redact. The picker will produce region sets, not one-off edits, so the batch workflow stays the centre of the tool. 2. OCR-driven automatic redaction. Detect text runs in the screenshot and redact the ones matching a pattern - email addresses, licence keys, card numbers, customer names from a supplied list - without hand-measuring a single coordinate. 3. Native screen capture. Grab a window, a display or a dragged rectangle directly on Windows and macOS, so capture, annotation and redaction are one pipeline instead of three tools. -------------------------------------------------------------------------------- EXAMPLES Work out the coordinates: captureflow inspect ticket.png Pixelate the address bar, ring it in red, point at the error: captureflow annotate ticket.png --out ticket-doc.png \ --pixelate 40,60,200,40,12 \ --box 36,56,208,48,red,3 \ --arrow 300,200,250,80,yellow,4 Order matters - this pixelates the box away again: captureflow annotate ticket.png --out oops.png \ --box 36,56,208,48,red,3 \ --pixelate 40,60,200,40,12 Redact forty screenshots the same way, checking first: captureflow redact ./tickets --out ./clean --regions redact.json captureflow redact ./tickets --out ./clean --regions redact.json --apply Convert while annotating: captureflow annotate photo.jpg --out photo-clean.png --blackout 10%,80%,80%,15%