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

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

All Implemented Interfaces:

ScorerIF

Direct Known Subclasses:

AbstractImgSampleScorer

public abstract class AbstractImgScorer
extends AbstractScorer
implements ScorerIF

Base interface to compute the score and confidence for a 2D still image. 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.

_tnBICache

private static final SoftReferenceMap<java.lang.Object,java.awt.image.BufferedImage> _tnBICache

Private static 'soft' cache from unique exhibit identifier to expanded (std) thumbnail image. This exists to avoid having to unpack thumbnail images repeatedly.

The (big) expanded images are held via SoftReferences to allow them to be ditched in case of memory shortage, and when individual thumbnails stop being used, and we don't cache new entries unless there is lots of free memory.

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.

rejectMainlyTransparentPoints

public static final AbstractImgScorer.ARGBPixelFilter rejectMainlyTransparentPoints

Filter to reject mainly-transparent ARGB samples.

AbstractImgScorer

public AbstractImgScorer()

Create simple non-parameterised instance.

AbstractImgScorer

public AbstractImgScorer(java.lang.String nameAndParameters)

Create parameterised version.

AbstractImgScorer

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

Create parameterised version.

callStillImageFactory

protected static java.awt.image.RenderedImage callStillImageFactory(java.util.concurrent.Callable<java.awt.image.RenderedImage> stillImageFactory)
                                                             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 abstract ScoreAndConf computeScoreAndConfidenceOnStillImage(java.lang.Object key,
                                                                   java.util.concurrent.Callable<java.awt.image.RenderedImage> stillImageFactory)
                                                            throws java.io.IOException

Compute score [-1,+1] and confidence[0,+1] for given image; never null. This routine must NOT alter the image.

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.

This is made public mainly so as to facilitate testing.

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

getSamplePoints

public static int[] getSamplePoints(java.awt.image.RenderedImage stillImage,
                                    int maxSamplePoints,
                                    AbstractImgScorer.ARGBPixelFilter filter)

Collect a set of 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

rejectMainlyTransparentPoints - if true then omit mainly transparent points

computeScoreAndConfidence

public ScoreAndConf computeScoreAndConfidence(SimpleExhibitPipelineIF dataSource,
                                              Name.ExhibitFull exhibitName)
                                       throws java.io.IOException

Implement core/generic compute method specially for image types. For any suitable 2D still image type that has a standard thumbnail, this uses calls the computeScoreAndConfidence(RenderedImage) method with that thumbnail.

We assume the standard thumbnail to be representative of the full image (and usually good enough for a human to make a judgement from) without requiring all the system resources of the full image.

For non-image types (or images with no thumbnails possible) this returns (0,0) to indicate that it does not have a view.

Specified by:

computeScoreAndConfidence in interface ScorerIF

Parameters:

dataSource - source of exhibit data and metadata; never null

exhibitName - full name of exhibit; must be syntactically valid and not null

Throws:

java.io.IOException - in case of I/O difficulties, or when a thumbnail is not currently available but may be later (upon retry)