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

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

All Implemented Interfaces:

ScorerIF

public final class SimpleHue
extends AbstractImgSampleScorer

Simple score/measure of presence of various key 'hues' in an image; never null. This scores an image highly if a suitable fraction (in a specified range) of sampled pixels is within one of a number of acceptable (wrapped) hue ranges (centre hue and tolerance) in an HSB (Hue, Saturation, Brightness) colour model.

The aim is to be able (for example) to give an image a good score if it contains a reasonable fraction of sky (blue) or skin (tone) or green (grass and trees).

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-random generator, to help avoid poor sampling of images with regular patterns in them.

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.
• Vector of target hues (from pixel HSB values).
• Vector of hue tolerances (max 50% either side, wrapped through zero).
• Vector of target percentages of pixels with given hue (0--100%).
• Vector of percentage tolerances (max 50% either side).

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

We may reject samples that are:

• Mainly transparent.
• Barely coloured, eg zero saturation or zero brightness in HSB colour space.

Author:

dhd

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.

SimpleHue

public SimpleHue()

Create simple non-parameterised instance.

SimpleHue

public SimpleHue(java.lang.String nameAndParameters)

Create parameterised version.

SimpleHue

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

computeScoreAndConfidenceOnStillImagePixelSamples

public ScoreAndConf computeScoreAndConfidenceOnStillImagePixelSamples(java.lang.Object key,
                                                                      java.util.concurrent.Callable<ROIntArray> stillImagePixelSamplesFactory)
                                                               throws java.io.IOException

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

Specified by:

computeScoreAndConfidenceOnStillImagePixelSamples in class AbstractImgSampleScorer

Parameters:

key - unique key identifying image for cacheing intermediate results for example; if null then this will not be cached

Returns:

assessment of the image, else (0,0) for a null image

Throws:

java.lang.IllegalArgumentException - for a null image factory

java.lang.IllegalStateException - for some problem retrieving the image

java.lang.IllegalArgumentException - for a null image factory

java.lang.IllegalStateException - for some problem retrieving the image

java.io.IOException

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