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

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

All Implemented Interfaces:

ScorerIF

public final class LocalSampler
extends AbstractImgScorer

Simple but configurable Scoring based on local pixel sampling; never null. Since this does not involve any global image operations, running time is nominally independent of image dimensions, ie in all case local image properties are sampled.

This can sample various pixel parameters such as R, G and B components, and can use the absolute values or available ranges.

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,

The confidence depends on the number of selected sample points that are available.

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

Parameters include:

• Pixel sample-set size.
• Pixel component to sample: A (alpha), R, G, B, Y (luminance), H, S, B.
• Pixel sampling method: value or median range (on grid centred on specified pixel).
• Pixel sample combination method: mean or median range.
• Fraction of outliers to discard for sample-combination median range computations.
• Mapping interpolation vector from sample combination value to score.
• Mapping interpolation vector from sample combination value to confidence.

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

Author:

dhd

MAX_COMPONENT_VALUE

private static final byte MAX_COMPONENT_VALUE

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

See Also:

Constant Field Values

MAPPING_INTERVALS

private static final int MAPPING_INTERVALS

Number of intervals in which to map score and confidence; strictly positive. Note that there will be one more parameters that this for each of the score and confidence mappings since the parameters mark the end-points of each interval, with linear interpolation between them.

Too small a value hinders a good fit to multi-modal distributions, too large a value makes the state space to explore unnecessarily large.

There is no point in having more intervals than distinct component values (from which this is driven), indeed there should be many fewer.

A power of two may help speed up some computations.

See Also:

Constant Field Values

scoreMappingParamBoundsBase

private static final ScorerParamInteger scoreMappingParamBoundsBase

Default base score mapping output value; never null. Because there are many parameters based on this, with this name as a prefix, we keep the name as short as possible.

We ensure that this prefix uniquely distinguishes this from all other parameters to give us the maximum possible choice of suffixes.

The perturbation value allows a reasonable state-space exploration speed.

There is no bias: there is no preferred/cheap perturbation direction.

scoreMappingParamsBounds

private static final java.util.List<ScorerParamInteger> scoreMappingParamsBounds

Immutable List of default mapping factors for the score from least to highest input values; never null. Always MAPPING_INTERVALS+1 entries.

scoreMappingParams

private final java.util.List<ScorerParamInteger> scoreMappingParams

Mapping factors for the score from least to highest input values; never null. Always MAPPING_INTERVALS+1 entries.

confidenceMappingParamBoundsBase

private static final ScorerParamInteger confidenceMappingParamBoundsBase

Default base confidence mapping output value; never null. Because there are many parameters based on this, with this name as a prefix, we keep the name as short as possible.

We ensure that this prefix uniquely distinguishes this from all other parameters to give us the maximum possible choice of suffixes.

The perturbation value allows a reasonable state-space exploration speed.

There is no bias: there is no preferred/cheap perturbation direction.

confidenceMappingParamsBounds

private static final java.util.List<ScorerParamInteger> confidenceMappingParamsBounds

Immutable List of default mapping factors for the confidence from least to highest input values; never null. Always MAPPING_INTERVALS+1 entries.

confidenceMappingParams

private final java.util.List<ScorerParamInteger> confidenceMappingParams

Mapping factors for the score from least to highest input values; never null. Always MAPPING_INTERVALS+1 entries.

pixelSampleMethodParamBounds

private static final ScorerParamEnum<SampleType> pixelSampleMethodParamBounds

Default pixel sample method; never null.

pixelSampleMethodParam

private final ScorerParamEnum<SampleType> pixelSampleMethodParam

Pixel sample method; never null.

sampleCombinationParamBounds

private static final ScorerParamEnum<SampleType> sampleCombinationParamBounds

Default sample combination method; never null.

sampleCombinationParam

private final ScorerParamEnum<SampleType> sampleCombinationParam

Pixel-value constituent to sample; never null.

componentParamBounds

private static final ScorerParamEnum<PixelComponent> componentParamBounds

Default pixel-value constituent to sample; never null.

componentParam

private final ScorerParamEnum<PixelComponent> componentParam

Pixel-value constituent to sample; never null.

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.

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.

LocalSampler

public LocalSampler()

Create simple non-parameterised instance.

LocalSampler

public LocalSampler(java.lang.String nameAndParameters)

Create parameterised version.

LocalSampler

public LocalSampler(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

trimOutliers

private static void trimOutliers(int[] sampleCounts,
                                 int nOutliers)

Trim the n outliers of each end of the supplied array of sample counts.

Parameters:

sampleCounts - array of non-negative sample count for each value x at index x; never null

nOutliers - strictly positive outlier count; less than half the total sum

mapRawValue

private static final int mapRawValue(int rawVal,
                                     java.util.List<ScorerParamInteger> mapping)

Compute (interpolated) mapping from raw value to score/confidence. The result is in the range permitted by the input mapping's min/max bounds.

samplePointRange

private int samplePointRange(java.awt.image.BufferedImage stillImage,
                             int x,
                             int y)

Take sample of area centred on specified point in image; null means point cannot be sampled, else [0,127]. We compute the median range of the appropriate component of the specified pixel and the 8 around it, skipping any that would be outside the image boundary (the specified point is assumed to be within the image) or that are returned as unsamplable by the the samplePoint() method.

We discard the highest and lowest values (as possible noise) and return the span of the remaining values.

We must be able to find at least 4 (four) samplable values else we must return null.

Returns:

-1 for an unsamplable point, else value in range [0,127] inclusive

samplePoint

private int 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 except where we are sampling the alpha value itself.

Returns:

-1 for an unsamplable point, else value in range [0,127] inclusive

getParameterDefsAndValues

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

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

Specified by:

getParameterDefsAndValues in interface ScorerIF

Overrides:

getParameterDefsAndValues in class AbstractScorer