org.hd.d.pg2k.ai.scorer.parameterised
Class SimpleExposure

java.lang.Object
  org.hd.d.pg2k.ai.scorer.AbstractScorer
      org.hd.d.pg2k.ai.scorer.AbstractImgScorer
          org.hd.d.pg2k.ai.scorer.parameterised.SimpleExposure

All Implemented Interfaces:

ScorerIF

public final class SimpleExposure
extends AbstractImgScorer

Simple score/measure of image "exposure" over random sample points; never null. This ignores outlier values of luminance (Y/brightness), and the wider the spread of the remainder normalised to the theoretical range the better and the more confident our prediction. This does not generate negative (bad) results, just good results for those images that seem to have good exposure by this simple metric.

The set of sample points is a grid spaced in a regular (though not a simple grid) pattern across the image. The layout of the sample points depends on the image size and aspect ratio, and is generated from a pseudo-randon generator, to help avoid poor sampling of images with regular patterns in them,

For example, if having discarded the few top and bottom Y values the remainder cover 90% of the available Y range, this returns a score of 90% of MAX.

The confidence depends on the number of selected sample points that are available; if all those chosen are available and fully opaque (no alpha) then the confidence is 1. If no chosen sample points are available and fully opaque then the confidence is 0. Partially-opaque points may be ignored or contribute pro-rata by opacity/alpha.

A single-pixel transparent image should result in a result of (0, 0) ie no range of luminance (Y), and no fully-opaque sample points.

Very small images will have all their pixels sampled, and so can in principle still achieve a MAX confidence.

This scoring method should run in constant time regardless of image size since it samples at most a fixed ceiling number of image points.

This may be most useful for continuous-tone true-colour/greyscale (eg JPEG) images.

Author:

dhd

MAX_BRIGHTNESS

private static final byte MAX_BRIGHTNESS

Max brightness returned by samplePoint (minimum is 0); strictly positive.

See Also:

Constant Field Values

USE_B_NOT_Y

private static final boolean USE_B_NOT_Y

If true then use the B of the HSB model (max of R, G and B), else use the weighted Y value from YUV.

See Also:

Constant Field Values

sampleSizeParamBounds

private static final ScorerParamInteger sampleSizeParamBounds

Min, default and max shift (power-of-two) for the target sample size; never null. This has a bias to lower values since this results in less work done.

sampleSizeParam

private final ScorerParamInteger sampleSizeParam

Target sample size for this instance; never null. Target number of sample points; strictly positive. If fewer sample points than this are available, then the result's confidence will drop in accordance with expected sample-variance noise reduction.

Reducing the sample size by a factor of x is assumed to increase the noise, and thus reduce the confidence, by a factor of sqrt(x).

Experience suggests that upwards of a thousand samples gives good consistency.

brightnessParamBounds

private static final ScorerParamInteger brightnessParamBounds

Min, default and max percentage of Y range that should be spanned for MAX score; never null.

brightnessParam

private final ScorerParamInteger brightnessParam

Percentage brightness range that should be spanned for MAX score for this instance; never null.

outlierParamBounds

private static final ScorerParamInteger outlierParamBounds

Min, default and max shift for the outlier fraction to remove; never null. Shift to get fraction/portion of the samples that are discarded from either end as potential noise; 3 or greater. A larger value discards fewer samples/values, but makes the measurement more sensitive to noise/grain and small highlights (etc). We always trim at least one outlier at each end.

A good shift value may line in the region of 3 to 7 thus discarding ~13% to ~1% of the outliers from either extreme.

outlierParam

private final ScorerParamInteger outlierParam

Outlier parameter value for this instance; never null.

SimpleExposure

public SimpleExposure()

Create simple non-parameterised instance.

SimpleExposure

public SimpleExposure(java.lang.String nameAndParameters)

Create parameterised version.

SimpleExposure

public SimpleExposure(java.lang.String baseName,
                      java.util.List<ScorerParam> parameters)

Create parameterised version.

createVariant

public ScorerIF createVariant(java.lang.String nameAndParameters)
                       throws java.lang.IllegalArgumentException

Simple non-static factory for the parameterised case.

Throws:

java.lang.IllegalArgumentException - for unparsable or inappropriate input

createVariant

public ScorerIF createVariant(java.lang.String baseName,
                              java.util.List<ScorerParam> parameters)
                       throws java.lang.IllegalArgumentException

Description copied from interface: ScorerIF

Create variant of same base Scorer with base name and parameters; never null. Most Scorers will provide a public constructor taking a String argument with the same effect, but this allows us to enforce the requirement in the interface (at the low cost of retaining and starting from something like the no-arg instance).

May be able to share some (immutable) state with the original instance, and the value returned is immutable and may not be new.

Throws:

java.lang.IllegalArgumentException - for unparsable or inappropriate input

computeScoreAndConfidence

public ScoreAndConf computeScoreAndConfidence(java.awt.image.RenderedImage stillImage)

Score the image for "exposure"; never null nor negative in any component.

Specified by:

computeScoreAndConfidence in class AbstractImgScorer

Parameters:

stillImage - non-null still 2D image; if greater than 256x256 pixels then will be internally scaled

Throws:

java.lang.IllegalArgumentException - for a null image

samplePoint

private java.lang.Byte samplePoint(java.awt.image.BufferedImage stillImage,
                                   int x,
                                   int y)

Take sample at given point in image; null means point cannot be sampled, else [0,127]. We regard points that are less than 50% opaque as being unsamplable.

Returns:

null for an unsamplable point, else brightness in range [0,127] inclusive

getParameterDefsAndValues

public java.util.List<ScorerParam> getParameterDefsAndValues()

Get parameter definitions and values (immutable) for this Scorer; never null.

Specified by:

getParameterDefsAndValues in interface ScorerIF

Overrides:

getParameterDefsAndValues in class AbstractScorer