Documentation / imagemagick.md
Core 11629ae · View or edit Markdown on GitHub ↗

ImageMagick: exact PNG details and comparison sheets

The schemaxis.imagemagick/1 document prepares raster details for reports, pixel inspection and side-by-side comparisons. Declare image IDs and captured local PNG sources, an optional exact crop, integer magnification and clockwise quarter turns. Choose a colour assumption and alpha policy explicitly. The optional contact sheet puts results into equal cells; its JSON index identifies each tile. It does not draw labels or certify font rendering.

Start with an editable example#

Use the baseline, changed crop/rotation, encoded-alpha flatten, or the comparison sheet. Replace /replace/with/grid.png with an absolute local PNG path. The tiny qualification grid is regenerated by a literal fixture generator. Studio offers equivalent editable starters and complete document-control forms.

{
  "version": "schemaxis.imagemagick/1",
  "operation": "raster",
  "images": [{
    "id": "detail",
    "source": "/absolute/captured-image.png",
    "crop": {"x": 40, "y": 20, "width": 160, "height": 120},
    "scale": 2,
    "quarterTurns": 1
  }],
  "colourPolicy": "require-srgb",
  "alpha": "preserve"
}

schemaxis plan input.json
schemaxis run input.json --executable /absolute/magick --output-directory fresh-run
schemaxis verify fresh-run

Configure ImageMagick through the ordinary private application configuration or pass --executable. ImageMagick 7 with PNG support runs in its own process; the host needs only Python 3.10+. Discovery and planning do not import the application. Latest stable provenance and the precisely qualified runtime are recorded in upstream.json and source-bound qualification; installation availability is a separate readiness axis.

Pixel and colour conventions#

Crop coordinates are integer pixels measured from the top-left, with x right and y down. Width/height count included samples, so x=1,width=2 selects columns 1 and 2. A crop must lie wholly inside its source. Omitting it retains the image. scale defaults to 1 and permits integer magnification through 8 by nearest neighbour replication. quarterTurns defaults to 0 and permits 0, 1, 2, 3 clockwise rotations. Order is crop, scale, rotate, then alpha policy.

Only non-interlaced RGB/RGBA8 PNG is accepted. Every input is opened as a bounded regular file and decoded independently before native processing. The decoder checks the PNG signature, CRCs, chunk order, compression/filter methods, exact bounded zlib length and all five row filters. It rejects palettes, greyscale, 16-bit samples, tRNS, APNG, ICC profiles, compressed metadata and unknown chunks. It accepts sRGB, standard sRGB gAMA+cHRM, and bounded pHYs/tEXt/tIME metadata. It rejects lone or conflicting colour assertions. Accepted metadata is stripped; physical pixel resolution, text and timestamps are not retained in publications.

colourPolicy defaults to require-srgb: an sRGB chunk or standard matching sRGB gAMA+cHRM pair must declare the samples. assume-srgb additionally accepts untagged input, recording that authored assumption in the summary. Neither option converts colour or establishes a missing profile's original meaning. Output PNGs are untagged RGBA8; the summary explicitly carries their sRGB interpretation. Use assume-srgb explicitly when chaining these PNGs into another raster recipe.

alpha defaults to preserve, retaining all RGBA samples, including RGB beneath zero alpha. RGB inputs receive alpha 255. flatten replaces alpha with 255 and blends each encoded sRGB channel with the declared background (default white): (channel * alpha + background * (255-alpha) + 127) // 255. This is nearest-integer sample arithmetic, not linear-light or colourimetric compositing. For example green [0,255,0,128] on [20,40,60] becomes [10,148,30,255]. Background has no effect in preserve mode; omit it there.

Contact sheets and publications#

Enable sheet to arrange prepared results row-major. columns defaults to 2 (and cannot exceed image count), padding defaults to 8 pixels, and the opaque sheet background defaults to white. Cells use the largest prepared width and height. Tiles occupy each cell's top-left and copy their complete RGBA samples, including transparent samples; they do not blend with the sheet background. Unused cells and padding retain the background. No automatic fit, trimming or resampling occurs.

Artifacts are ordered image-00.png, image-01.png, ... in declared order, then optional sheet.png, then raster-summary.json (text kind). The summary contains IDs, source and output dimensions, observed colour declaration, authored colour/alpha policy, exact RGBA sample hashes and sheet indices/positions. Source captures are retained evidence rather than extra publications. The native command and its exact input hashes, generated launcher, scoped policy and stdout/stderr remain available for inspection.

There are 1–8 sources, at most 8MiB each, at most 4096 pixels per side, and 1,048,576 combined source pixels. All image publications plus the optional sheet together must also stay within 1,048,576 pixels. Child processes use one thread, CPU/address-space/file-size limits, a 128MiB native pixel cache and no map/disk spill. One total deadline and shared owned process cancellation cover the complete run. Choose smaller crops/scales if budgets are exceeded.

Workflow handoff and reuse#

The route accepts verified image artifacts through ordinary $artifact references in /images/N/source, captures their bytes and publishes regular PNGs. Use colourPolicy: "assume-srgb" when consuming a producer's untagged PNG whose encoded-sRGB interpretation you have established. The PNG decoder still rejects unsupported data. Normal scheduling supports byte-bound source reuse: unchanged inputs reuse a verified attempt, while changing bytes at the same path creates a new attempt. Common composition and finite studies work without custom native expressions. No native handle crosses processes. No general format/colour conversion, native project save, interactive inspection, MPI or temporal batch API is advertised.

Verification and recovery#

The qualification launcher runs baseline, changed-crop/rotation, flatten and sheet cases through normal execution. Expected pixels come from the literal 3x2 RGBA grid, independent Python integer transforms and a standard-library PNG decoder, not identify, native decode, output existence or a success flag. Every pixel/channel is compared exactly. The fixture includes alpha 0, 64, 128 and 255 and nonzero hidden RGB. Native quantum depth and HDRI therefore cannot silently change rounding or erase hidden channels. Qualification covers that lossless subset; it does not certify arbitrary images, colour appearance, colour management, typography or unsupported PNG modes.

INVALID_RASTER_SOURCE means choose an absolute regular local PNG within the byte budget. INVALID_RASTER_PNG reports a corrupt or unsupported PNG and explains the chunk/mode; re-export a supported PNG deliberately. RASTER_COLOUR_REQUIRED requires explicit sRGB provenance or authored assume-srgb. RASTER_CROP_OUTSIDE requires a crop inside the source. RASTER_PIXEL_BUDGET requires fewer or smaller images, crops, scale or sheet. INVALID_RASTER_ID requires distinct ASCII IDs. INVALID_RASTER_ALPHA requires omitting an unused preserve-mode background. VERIFICATION_FAILED means retained data, recipe, policy, native submission or pixels differ; retain the failed evidence and create a new run after repair. RUNNER_TIMED_OUT/RUNNER_CANCELLED never publish a successful run.

Native recipes receive only trusted captured/output filenames. They expose no format prefixes, arbitrary options, user expressions, delegates, SVG/PDF/URLs or scripts. A child-local policy denies all delegates/filters/modules/coders and permits only PNG plus the exact captured/output paths. A minimal environment prevents inherited ImageMagick configuration overrides; no user PATH is changed. These restrictions are verified with deliberate native deny probes. Source and receipt hashes are integrity checks, not signatures against a dishonest author.

Public API references: CLI crop, sample, rotate, alpha, compose, security policy and PNG specification. See the operation reference and completion review.