SCRYDOSBox-XReferenceFilesimage_compareAlso in MAME
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
series_capture wrote: 14 frames of a video in which a brick falls. The rectangle is that brick's.In the series, at which frames does the second brick's rectangle change, and by how many pixels?
image_compare(method="region", manifest="./tmp/demos/tour/files/series/manifest.json",
crop=[386, 148, 60, 16], measure="changed_pixels"){
"summary": "image_compare region: changed_pixels, 4 transitions over 14 frames",
"frames": 14,
"transitions": [
[103, 32],
[104, 944],
[105, 40],
[106, 8]
],
"gaps": [1, 1, 1]
}The rectangle changes at four of the 14 frames, and at frame 104, 944 of its pixels change at once: the brick is gone. Each of the gaps is 1, so the changes are on consecutive frames.
The whole reply
{
"summary": "image_compare region: changed_pixels, 4 transitions over 14 frames",
"status": "ok",
"measure": "changed_pixels",
"crop": [386, 148, 60, 16],
"frames": 14,
"start": {
"available": false,
"why": "`changed_pixels` counts a change from the frame before, and the first frame has none"
},
"transitions": [
[103, 32],
[104, 944],
[105, 40],
[106, 8]
],
"gaps": [1, 1, 1],
"transitions_total": 4,
"path": "./tmp/demos/tour/files/series/track-1.json",
"manifest": "./tmp/demos/tour/files/series/manifest.json"
}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,regionorgolden, as above.- a string, default
"" - The first PNG for
image, or the first manifest forseries. 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 butgolden. Left out, the whole picture. - shift array of integer, optional
- For
image:[dx, dy], how farbis 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
regionandgolden: the series to read, by the path of its manifest. - measure string, default
"" - For
region, what is followed: the rectangle'ssignature, itschanged_pixelssince the frame before, or itsmatchwithref. 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 equalref, above 0 and at most 1. Left out, 0.98. - limit integer, optional
- For
regionandgolden: 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 ofmanifest. - checksums string, default
"" - For
golden: the file of reference checksums, in the formatshasum -a 256writes.
What comes back
- differing_pixels
- For
image: how many pixels differ by more thantolerance. 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 ofa. - first_differing
- For
series: the first frame that differs, with itsframenumber, itsdiffering_pixelsand itsbbox. - differing
- For
series: how many paired frames differ. Forgolden: the names of the files whose checksum differs. - transitions
- For
region: each change as[frame, value], the firstlimitof them;transitions_totalcounts 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
- An argument the method does not take (
bad_argument). - Two pictures of different sizes with no
cropthat lies inside both (bad_argument). - A
cropthat leaves the picture, or ashiftthat moves it wholly off itself (bad_argument). - A path that is relative or missing, or a file that is no PNG or no
scry-series/1manifest (bad_argument). - A manifest with a frame changed since it was written, or a row edited by hand (
bad_argument). - A series that never changes, two series with no frame number in common, a region that never changes, or checksums that name no file examined (
control_silent).
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
seriespairs frames by number. Frames only one series has come back inonly_in_aandonly_in_bas[first, last]ranges.regionanswersstart, the first frame and its value, then the transitions.gapscounts the frames between one transition and the next.goldenpairs files and checksum lines by file name.matchedcounts the equal ones,missinglists lines with no file,extrafiles with no line.- The reply repeats the arguments it took, each path in full. For
image,aandbcome back with the file'spathandsha256.
Related tools
The contract your client receives
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.