images

type Bucket struct {
	// Pictures is how many were judged in this bucket.
	Pictures int
	// Exact is how many had no channel differ by more than Gate. It is the
	// criterion.
	Exact int
	// Identical is how many of those had no channel differ AT ALL, so a
	// reader can see how much of the agreement is bit equality and how much
	// the gate bought. One gate applies to every filter, which is a loosening
	// for the lossless ones — they could defensibly be held to nought — and
	// this is the count that says whether the loosening bought anything.
	Identical int
	// Inverted is how many agreed with the judge's complement instead.
	Inverted int
	// Calibrated is how many of this bucket's pictures name a CIE-based space
	// in their own dictionary.
	//
	// It is nought in the direct bucket by construction, since a calibrated
	// picture is converted whatever the listing said. In the converted bucket
	// it is how much of that bucket the document itself accounts for — and it
	// is NOT what conformance#20's rule moved, which is a much smaller number:
	// most calibrated pictures are ICCBased or Indexed, which the listing
	// already called converted. What moved is what the listing called gray or
	// rgb, and that is the difference between two runs rather than a column
	// in either.
	Calibrated int
	// Diffs holds the magnitude of each picture that differed.
	Diffs []Difference
}

type BucketCounts struct {
	Pictures int `json:"pictures"`
	Exact    int `json:"exact"`
	// Identical is how many of the exact ones differed by nothing at all, so
	// bit equality can be told from agreement the gate bought.
	Identical int `json:"identical"`
	Inverted  int `json:"inverted"`
	Differing int `json:"differing"`
	// Calibrated is how many of these pictures name a CIE-based /ColorSpace in
	// their own dictionary. Nought in the direct bucket by construction, and
	// not the count of what conformance#20's rule moved; see Bucket.Calibrated.
	Calibrated int `json:"calibrated,omitempty"`
	// Terms is the spread of each magnitude over the differing pictures,
	// absent when none differed. A pointer because 0 is a real answer here —
	// a bucket whose worst peak is nought is not the same as one with nothing
	// to disagree about — and omitempty cannot tell those apart.
	Terms *Terms `json:"terms,omitempty"`
}

type Counts struct {
	// Pictures is how many were judged.
	Pictures int
	// SizePaired is how many were matched to the judge's picture by SIZE
	// rather than by object number.
	//
	// PairedBy's own note says a run whose size share is large is a run whose
	// numbers are worth less, "and that has to be visible". It was not: the
	// field was recorded per picture and no report or record carried it, so
	// the share could not be read from a run at all. conformance#13 found 144
	// of 173 apparent inversions were this fallback pairing pictures that had
	// nothing to do with each other, which is what makes the share worth
	// printing beside the counts it qualifies rather than kept for whoever
	// thinks to ask.
	SizePaired int
	// Unmatched is how many the other implementation had no picture for.
	Unmatched int
	// Remapped is how many carried a /Decode array, which we apply and
	// pdfimages does not, so the two sides were not asked the same question.
	// They are counted here rather than as disagreements: on a one-bit mask a
	// /Decode of [1 0] inverts every pixel, which reads as total disagreement
	// and is none.
	Remapped int
	// RawBits is how many the judge wrote as samples rather than as colour,
	// which is every one-bit picture whose space is an index or a tint. They
	// are counted here for the same reason as Remapped: the two sides were
	// not asked the same question. 1070 pictures in 17 of the 2598 forms.
	RawBits int
	// Direct is the pictures whose colour space needed no conversion, which
	// are the ones the agreement figure is computed over.
	Direct Bucket
	// Converted is the rest, tallied with their own magnitudes so that the
	// claim "this is colour arithmetic and not a decoder" can be checked
	// rather than assumed.
	Converted Bucket
}

type Difference struct {
	// Share is the fraction of pixels where some compared channel differs by
	// more than Gate, or -1 when the picture could not be judged. It is a
	// REPORT and not a budget: the count budget is zero, so Share being nought
	// and Peak being within Gate are the same statement.
	Share float64
	// Peak is the largest absolute channel difference anywhere in the
	// picture, in levels of 255. This is the criterion.
	Peak int
	// MSE is the mean squared error over every compared channel, in levels
	// squared — pdfium's units at testing/image_diff.cpp:181 and FFmpeg's
	// omse at dct.c:256.
	MSE float64
	// Mean is the signed mean error over every compared channel, ours minus
	// theirs, in levels — FFmpeg's ome. It is the term that catches BIAS,
	// which is what the bisection this replaced could not see.
	Mean float64
	// Inverted says the direct comparison failed the gate and the picture
	// against the judge's COMPLEMENT passes it.
	//
	// pdfimages writes a STENCIL with the opposite polarity to the samples it
	// holds: an image with /ImageMask true, or a stream a picture names as its
	// /Mask. That is a convention, not a disagreement — and it is worth
	// telling apart from a real one, because "identical up to inversion" and
	// "wrong" look the same in a magnitude and only one of them needs looking
	// into.
	//
	// Which side is right was measured rather than assumed. On a 644-byte
	// document whose 8x8 mask has its left half masked out and its right half
	// painted, poppler's own pdftoppm paints the right half, which is what
	// PDF 32000-1 8.9.6.2 says, pdfimages writes the left one, and ours
	// agrees with the rendering.
	//
	// It is about being a stencil and nothing else. Not about JBIG2: 27 of
	// the 28 in us-opm are CCITT, one is Flate, and the minimal document has
	// no filter. Not about soft masks, which are the one kind pdfimages
	// leaves alone.
	//
	// Not every complement this reports is that convention. When a page draws
	// many uniform pictures of one size, match pairs them by size and order
	// and pairs a black one with a white one; see
	// https://github.com/go-pdfkit/conformance/issues/13.
	Inverted bool
}

type FilterCounts struct {
	Filter   string `json:"filter"`
	Pictures int    `json:"pictures"`
	// Unmatched and Remapped are the pictures no comparison was made of.
	Unmatched int `json:"unmatched"`
	Remapped  int `json:"remapped"`
	// SizePaired is how many were paired by size rather than by object. A
	// large share here devalues every figure on the line beside it.
	SizePaired int `json:"sizePaired,omitempty"`
	// RawBits is the pictures the judge wrote as samples rather than as
	// colour, which is a third way of not being asked the same question.
	RawBits int `json:"rawBits,omitempty"`
	// Direct and Converted are the two buckets, absent when empty. The
	// agreement figure is Direct's and never the two added together.
	Direct    *BucketCounts `json:"direct,omitempty"`
	Converted *BucketCounts `json:"converted,omitempty"`
}

type Hang struct {
	Path string `json:"path"`
	Page int    `json:"page"`
	Tool string `json:"tool"`
}

type Missing string

type Options struct {
	// Pages is how many pages of each document to take the pictures of; 0
	// means the first only.
	Pages int
}

type Result struct {
	Path string
	Page int
	// Name is the resource name the page draws it by.
	Name string
	// Filter is the image format it was stored in, empty for plain samples.
	Filter string
	// Stencil says render returned this as a MASK rather than as a picture —
	// a /ImageMask true stencil, or a stream some picture named as its /SMask
	// or /Mask. It decides what channel the two sides are compared in.
	Stencil bool
	// RawBits says pdfimages wrote this picture's SAMPLES rather than its
	// colour. ImageOutputDev.cc:642 picks PNGWriter::MONOCHROME whenever the
	// colour map has one component and one bit, and then writes
	// `str->getChar() ^ invert_bits` -- the bits themselves, with the colour
	// space never consulted. For a one-bit DeviceGray that is the same thing:
	// the sample IS the level. For an index or a tint it is not, and
	// cerfa_10074.pdf is the case that found it -- an Indexed palette of
	// 808080 and ffffff, drawn by us as the mid grey it says and written by
	// the judge as a bit.
	RawBits bool
	// Decoded says a /Decode array shaped our samples. pdfimages writes the
	// samples as stored, so this picture and theirs are not the same question
	// and are counted apart rather than as a disagreement.
	Decoded bool
	// PairedBy says how this picture was matched with the judge's: "object"
	// when both sides named the same object number, "size" when it fell back
	// to the first unclaimed picture of the same size. Empty when nothing was
	// paired. A run whose size share is large is a run whose numbers are worth
	// less, and that has to be visible.
	PairedBy string
	// Space is the colour space pdfimages reports for the judge's picture:
	// gray, rgb, cmyk, lab, icc, index, sep, devn, or "-" for a mask. It is
	// empty when no row could be read for it.
	Space string
	// Converted says poppler had to convert that space to reach RGB, so a
	// per-channel difference on this picture is colour arithmetic and not
	// codec error. Those are tallied apart; see the package comment.
	Converted bool
	// Calibrated says the picture's OWN dictionary names a CIE-based colour
	// space. It is what makes Converted true for a picture the listing calls
	// gray or rgb, which poppler does for CalGray and CalRGB although it
	// converts them (conformance#20). It is kept beside Converted rather than
	// folded into it so a bucket can say how much of itself the document
	// accounts for, which is not the same as how much the rule moved.
	Calibrated bool
	// Size is what the picture came out as.
	W, H int
	// Difference is how far apart the two came out, or Share -1 when there
	// was no comparison, which Note explains.
	Difference
	// Missing says which side had nothing, when nothing could be compared.
	// It is a field rather than a reading of Note because a baseline has to
	// count these apart: a run that agrees less because ours stopped opening
	// documents and a run that agrees less because it decoded them wrongly
	// are different events, and a total that lumps them says neither.
	Missing Missing
	// Tool is the poppler tool that did not finish, when Missing is Hung. It
	// is empty otherwise. A hang is only useful as data if it says which of
	// the three invocations it was, because they fail independently.
	Tool string
	Note string
}

type Spread struct {
	Median float64 `json:"median"`
	// Worst is the value furthest from zero, WITH ITS SIGN, so that a signed
	// mean says which way the bias ran and not only how big it was.
	Worst float64 `json:"worst"`
}

type Summary struct {
	Population string `json:"population"`
	// Documents is how many were looked at, which is not how many were
	// judged: a document that draws no pictures contributes none.
	Documents int `json:"documents"`
	// Refused is how many documents ours would not open or draw, and the
	// judge would. This is the count that is a defect.
	Refused int `json:"refused"`
	// Unopenable is how many neither would open. A corpus is full of these
	// and they say nothing about a decoder, but a population's real size is
	// its documents minus these and a rate quoted without them is quoted over
	// the wrong denominator.
	Unopenable int `json:"unopenable"`
	// Declined is how many pages ours drew pictures for and the judge took
	// none out of, so there was nothing to compare them with.
	Declined int `json:"declined"`
	// Unseen is how many pictures the judge took out, under an object ours
	// produced nothing for -- the direction the pairing could not see at all
	// until it was counted. omitempty, so records written before it keep
	// their shape.
	Unseen int `json:"unseen,omitempty"`
	// Repeated is how many of the judge's rows name an object we compared
	// once. It is the scale of a difference in UNIT, not in fidelity:
	// pdfimages lists one row per draw and Images returns one entry per
	// object.
	Repeated int `json:"repeated,omitempty"`
	// Hung names the documents a poppler tool would not finish on, with the
	// tool. A document that was skipped because the judge hung is not a
	// document that scored badly, and the two are indistinguishable in a
	// total, so these are carried by name rather than as a count. Absent when
	// nothing hung.
	Hung    []Hang         `json:"hung,omitempty"`
	Filters []FilterCounts `json:"filters"`
}

type Terms struct {
	Share Spread `json:"share"`
	Peak  Spread `json:"peak"`
	MSE   Spread `json:"mse"`
	Mean  Spread `json:"mean"`
}