org.hd.d.pg2k.ai.scorer
Class AbstractImgSampleScorer

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

All Implemented Interfaces:

ScorerIF

Direct Known Subclasses:

LocalSampler, SimpleExposure, SimpleHue

public abstract class AbstractImgSampleScorer
extends AbstractImgScorer
implements ScorerIF

Base interface to compute the score and confidence for a 2D still image using pixel ARGB sampling. The run-time and memory (etc) consumption of these sampling image Scores should be bounded by the upper limit on sample-set size, and thus potentially lower than a generic image Scorer.

All methods in this interface are guaranteed to be "safe" in so far as they will complete in "reasonable" time with reasonable heap memory (and other resource, eg stack) and without doing anything that wouldn't be allowed in a minimal Applet/JWS sandbox.

All classes implementing this interface should be completely thread-safe in their implementation of the computeScoreAndConfidence() method, and preferably purely functional (no visible side-effects), with as many concurrent threads as required safely doing separate computations in any one instance.

Classes implementing this interface should, where possible, do their calculations using integer arithmetic, since FPUs to support float/double calculations may be a scarce resource on newer highly-threaded CPUs such as Sun's Niagara.

TODO: At least tie the cache to the AEP/pipeline, not static.

_sampleCache

private static final MemoryTools.SoftReferenceMap<java.lang.Object,ROIntArray> _sampleCache

Private static 'soft' cache from unique exhibit identifier to pixel sample. This exists to avoid having to unpack, decode and sample thumbnail images repeatedly.

The samples are held via SoftReferences to allow them to be ditched in case of memory shortage, and when individual images stop being used.

The cache key is the (full) exhibit name plus other static attributes on the basis that thumbnails hardly ever change once created. This also means that we will stop hitting any thumbnail caches in the data pipeline once we have fetched a thumbnail once.

This cache is thread-safe and highly concurrent.

This cache is shared between all derived image Scorer classes.

TODO: Deal with the case when a thumbnail IS changed/improved.

MAX_SAMPLE_SIZE_POWER

public static final int MAX_SAMPLE_SIZE_POWER

Power of two of (hard) limit on maximum sample size for these image samplers; strictly positive. Sample sizes up to this may be more efficiently handled/cached by getSamplePoints(); above this threshold results may simply be capped in size.

See Also:

Constant Field Values

AbstractImgSampleScorer

public AbstractImgSampleScorer()

Create simple non-parameterised instance.

AbstractImgSampleScorer

public AbstractImgSampleScorer(java.lang.String nameAndParameters)

Create parameterised version.

AbstractImgSampleScorer

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

Create parameterised version.

callStillImagePixelSamplesFactory

protected static ROIntArray callStillImagePixelSamplesFactory(java.util.concurrent.Callable<ROIntArray> stillImagePixelSamplesFactory)
                                                       throws java.io.IOException

Call the factory to retrieve a still image, handling wrapped IOExceptions and timeouts specially.

Throws:

java.io.IOException - if the factory threw IOException

java.lang.IllegalStateException - if the factory throws something unrecognised

computeScoreAndConfidenceOnStillImage

public final ScoreAndConf computeScoreAndConfidenceOnStillImage(java.lang.Object key,
                                                                java.util.concurrent.Callable<java.awt.image.RenderedImage> stillImageFactory)
                                                         throws java.io.IOException

Convert the RenderedImage to pixel samples for our derived classes. This may cache the underlying samples.

This is final to prevent a derived sampling Scorer from getting at this directly.

Specified by:

computeScoreAndConfidenceOnStillImage in class AbstractImgScorer

Parameters:

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

stillImageFactory - produces on demand a non-null still 2D image or null if not possible; if greater than 256x256 pixels then will be internally scaled; never null

Throws:

java.lang.IllegalArgumentException - for a null image

java.io.IOException

computeScoreAndConfidenceOnStillImagePixelSamples

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

Compute score [-1,+1] and confidence[0,+1] for given image; never null. This is made public mainly so as to facilitate testing.

Note that the underlying factory may legitimately throw IOException, especially InterruptedIOException, in case of transient problems that indicate that a retry should probably be attempted later.

Parameters:

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

stillImage - non-null ARGB pixel value samples from a still 2D image

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.io.IOException

getUnfilteredSamplePoints

public static int[] getUnfilteredSamplePoints(java.awt.image.RenderedImage stillImage,
                                              int maxSamplePoints)

Collect a set of unfiltered ARGB samples from the image. This may return less than the number of samples requested, eg because the image does not have that many pixels or because we are rejecting 'transparent' points.

All samples returned are from unique pixels in the source image.

If the number of points requested greater than or equal to the number of image pixels then all pixels are 'sampled' and returned, else a pseudo-random (but consistent) sample set is returned.

The order of sample pixels is explicitly undefined since each sample should be treated independently of its position in the sample set.

This is made public mainly to assist with testing.

Parameters:

stillImage - still image (eg thumbnail) to sample pixels from; never null nor zero-sized

maxSamplePoints - maximum number of samples to collect; strictly positive