SCRYMAMEReferenceFilesimage_compareAlso in DOSBox-X

MAMEFiles

image_compare

Compare two pictures, two series of frames, or one region across a series, and get the difference as numbers.

image_compare(method, a="", b="", crop=null, shift=null, tolerance=null, manifest="", measure="", ref="", threshold=null, limit=null, dir="", checksums="")

Try it

On two frames of the series the Gridlee example of series_capture wrote, frames 557 and 581. No machine is running.
Ask

How different are frames 557 and 581 of the series?

Call
image_compare(method="image", a="./tmp/demos/tour/series/f000557.png",
    b="./tmp/demos/tour/series/f000581.png")
Reply 7 of 12 fields
{
  "summary": "image_compare image: 8975 pixels differ over 256x240, bbox [4, 17, 242, 213]",
  "differing_pixels": 8975,
  "bbox": [4, 17, 242, 213],
  "max_delta": [255, 255, 255],
  "width": 256,
  "height": 240,
  "tolerance": 0
}

8975 pixels differ between the two 256x240 pictures, all inside the rectangle bbox: 242 wide and 213 high, from (4, 17). A tolerance of 0 counts any difference.

The whole reply
JSON
{
  "summary": "image_compare image: 8975 pixels differ over 256x240, bbox [4, 17, 242, 213]",
  "status": "ok",
  "differing_pixels": 8975,
  "bbox": [4, 17, 242, 213],
  "max_delta": [255, 255, 255],
  "width": 256,
  "height": 240,
  "crop": [0, 0, 256, 240],
  "shift": [0, 0],
  "tolerance": 0,
  "a": {"path": "./tmp/demos/tour/series/f000557.png", "sha256": "<volatile>"},
  "b": {"path": "./tmp/demos/tour/series/f000581.png", "sha256": "<volatile>"}
}

The four methods

method what it compares
image Two PNGs, pixel by pixel: how many pixels differ, and where.
series Two series, frame by frame: how many frames are equal, and the first that differs.
region One rectangle across a series: the frames at which it changes.
golden A series or a folder of PNGs against a file of reference checksums.

Arguments

method one of "image", "series", "region", "golden", required
image, series, region or golden, as above.
a string, default ""
The first PNG for image, or the first manifest for series. An absolute path, or one starting with ~.
b string, default ""
The second PNG or manifest, compared with a.
crop array of integer, optional
The rectangle to compare, [x, y, width, height], for every method but golden. Left out, the whole picture.
shift array of integer, optional
For image: [dx, dy], how far b is moved before the two are compared. Left out, no move.
tolerance integer, optional
For image: the difference in one colour component still counted as equal, 0 to 255. Left out, 0.
manifest string, default ""
For region and golden: the series to read, by the path of its manifest.
measure string, default ""
For region, what is followed: the rectangle's signature, its changed_pixels since the frame before, or its match with ref. Left out, signature.
ref string, default ""
For the measure match: the PNG, of the crop's size, the rectangle is compared with.
threshold number, optional
For match: the fraction of the rectangle's pixels that must equal ref, above 0 and at most 1. Left out, 0.98.
limit integer, optional
For region and golden: how many items each list shows, 1 to 1000. Left out, 40; the whole count is beside the list.
dir string, default ""
For golden: a folder of PNGs to check, in place of manifest.
checksums string, default ""
For golden: the file of reference checksums, in the format shasum -a 256 writes.

What comes back

differing_pixels
For image: how many pixels differ by more than tolerance. Zero means the two are equal over the rectangle compared.
bbox
For image: the rectangle that holds every differing pixel, [x, y, width, height] in the coordinates of a.
first_differing
For series: the first frame that differs, with its frame number, its differing_pixels and its bbox.
differing
For series: how many paired frames differ. For golden: the names of the files whose checksum differs.
transitions
For region: each change as [frame, value], the first limit of them; transitions_total counts them all.
path
For region: a JSON file written beside the manifest, with every transition and each frame's value.
All 32 reply fields
  • a (object or string)
  • b (object or string)
  • bbox (array or object)
  • checksums (string)
  • crop (array)
  • differing (integer or array)
  • differing_pixels (integer)
  • differing_total (integer)
  • dir (string)
  • extra (array)
  • extra_total (integer)
  • first_differing (object)
  • frames (integer)
  • gaps (array)
  • height (integer)
  • identical (integer)
  • manifest (string)
  • matched (integer)
  • max_delta (array)
  • measure (string)
  • missing (array)
  • missing_total (integer)
  • only_in_a (array)
  • only_in_b (array)
  • pairs (integer)
  • path (string)
  • shift (array)
  • start (array or object)
  • tolerance (integer)
  • transitions (array)
  • transitions_total (integer)
  • width (integer)

What it refuses

Why it works this way

image compares the colours two pictures show, so an indexed PNG and an RGB one of the same screen are equal. golden compares file bytes through their checksums, so those two files differ.

Two pictures of different sizes are refused unless a crop lies inside both. A tool that shows a picture enlarges it by its scale, so take both at scale=1 before comparing them.

A crop that leaves the picture is refused, never padded: a padded crop would compare pixels nobody drew.

More on why
  • series pairs frames by number. Frames only one series has come back in only_in_a and only_in_b as [first, last] ranges.
  • region answers start, the first frame and its value, then the transitions. gaps counts the frames between one transition and the next.
  • golden pairs files and checksum lines by file name. matched counts the equal ones, missing lists lines with no file, extra files with no line.
  • The reply repeats the arguments it took, each path in full. For image, a and b come back with the file's path and sha256.
The contract your client receives
Text
Compare PNGs, series or a region of one, in numbers. `crop` [x, y, w, h]; `limit` 1..1000
(default 40) cuts a list, its count beside it. Replies also echo the arguments they took.

`image`: PNGs `a`, `b`; two sizes need `crop`; `shift` [dx, dy] moves `b`; `tolerance`
0..255. Reply: `differing_pixels`, `bbox`, `max_delta`, `width`, `height`.

`series`: `scry-series/1` manifests `a`, `b`. Reply: `pairs`, `identical`, `differing`,
`first_differing`, `only_in_a`, `only_in_b`.

`region`: `crop` of `manifest` by `measure`: `signature`, `changed_pixels`, or `match`
against `ref` at `threshold` (0.98). Reply: `start`, `transitions`, `gaps`,
`transitions_total`, `frames`, `path`.

`golden`: `manifest` or `dir` against `checksums` (`shasum -a 256`). Reply: `matched`,
`differing`, `missing`, `extra`, `differing_total`, `missing_total`, `extra_total`.

Refused: an argument the method does not take; `control_silent` when nothing can differ.

Reads files, and `region` writes one, `path`: it needs no machine. Every path is absolute or starts with `~`.

Reference: REFERENCE.md, Media files.
Tools