Gist (OpenIMAJ master project 1.3.10 API)

java.lang.Object
- org.openimaj.image.feature.global.Gist<IMAGE>

Type Parameters:

IMAGE - The type of image. MBFImage and FImage are supported; other types might not work.

All Implemented Interfaces:

ImageAnalyser<IMAGE>
```
@Reference(type=Article,
           author={"Oliva, Aude","Torralba, Antonio"},
           title="Modeling the Shape of the Scene: A Holistic Representation of the Spatial Envelope",
           year="2001",
           journal="Int. J. Comput. Vision",
           pages={"145","","175"},
           url="http://dx.doi.org/10.1023/A:1011139631724",
           month="May",
           number="3",
           publisher="Kluwer Academic Publishers",
           volume="42",
           customData={"issn","0920-5691","numpages","31","doi","10.1023/A:1011139631724","acmid","598462","address","Hingham, MA, USA","keywords","energy spectrum, natural images, principal components, scene recognition, spatial layout"})
public class Gist<IMAGE extends Image<?,IMAGE> & SinglebandImageProcessor.Processable<Float,FImage,IMAGE>>
extends Object
implements ImageAnalyser<IMAGE>
```
Implementation of the "Gist" spatial envelope feature. Based on (and tested against) the original Matlab implementation from http://people.csail.mit.edu/torralba/code/spatialenvelope/, and designed to produce comparable features.
The Gist or Spatial Envelope is a very low dimensional representation of the scene. Gist encodes a set of perceptual dimensions (naturalness, openness, roughness, expansion, ruggedness) that represents the dominant spatial structure of a scene. These perceptual dimensions are reliably estimated using coarsely localized spectral information from the image.
Implementation notes: This class supports both fixed and variable size Gist. In the fixed size mode, the image is resized and centre-cropped to a pre-defined size (allowing the Gabor filters to be pre-computed and reused). In the variable size mode the Gabor filters will be re-computed as necessary if the image size changes. For computing features to compare images, fixed size mode makes more sense.
Example usage for image comparison:
```
 FImage i1, i2 = ...
 Gist fsg = new Gist(256, 256);

 fsg.analyseImage(i1);
 FloatFV f1 = fsg.getResponse();

 fsg.analyseImage(i2);
 FloatFV f2 = fsg.getResponse();

 double d = FloatFVComparison.SUM_SQUARE.compare(f1, f2);
 
```
The ability to generate a visualisation of the current descriptor in the same way as provided by the original Matlab code is given by the visualiseDescriptor(int) method.
Author:

Jonathon Hare (jsh2@ecs.soton.ac.uk)

Field Summary

Fields
Modifier and Type	Field and Description
`int`	`boundaryExtension` The amount of padding to add before convolving with the Gabor functions
`static int`	`DEFAULT_BOUNDARY_EXTENSION` The default amount of padding to apply before convolving with the Gabor filters
`static int`	`DEFAULT_NUMBER_OF_BLOCKS` The default number spatial blocks
`static int[]`	`DEFAULT_ORIENTATIONS_PER_SCALE` The default number of filter orientations per scale (from HF to LF)
`static int`	`DEFAULT_PREFILTER_FC` The default number of cycles per image for the pre-filter Gaussian
`static int`	`DEFAULT_SIZE` Default image size (both height and width) for fixed size Gist
`protected boolean`	`fixedSize`
`protected FImage[]`	`gaborFilters`
`protected int`	`imageHeight`
`protected int`	`imageWidth`
`int`	`numberOfBlocks` The number of blocks in each direction
`protected int[]`	`orientationsPerScale`
`int`	`prefilterFC` The number of cycles per image for the pre-filter Gaussian
`protected FloatFV`	`response`

Constructor Summary

Constructors
Modifier	Constructor and Description
	`Gist()` Construct a fixed size Gist extractor using the default values.
	`Gist(boolean fixedSize)` Construct a variable or fixed size Gist extractor using the default values.
`protected`	`Gist(int[] orientationsPerScale)`
	`Gist(int[] orientationsPerScale, boolean fixedSize)` Construct a variable or fixed size Gist extractor with the given number of orientations per scale for the Gabor jet.
	`Gist(int width, int height)` Construct a fixed-size Gist extractor, with the given image size and the default number of orientations per scale for the Gabor jet.
	`Gist(int width, int height, int[] orientationsPerScale)` Construct a fixed-size Gist extractor, with the given image size and number of orientations per scale for the Gabor jet.
	`Gist(int width, int height, int[] orientationsPerScale, boolean fixedSize)` Construct a variable or fixed size Gist extractor with the given number of orientations per scale for the Gabor jet.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`analyseImage(IMAGE image)` Analyse an image.
`protected int`	`computeNumberOfSamplingBlocks()` Compute the number of sampling blocks that are used for every filter.
`protected void`	`extractGist(IMAGE image)`
`FloatFV`	`getResponse()` Get the response vector from the previous call to `analyseImage(Image)`.
`protected void`	`sampleResponses(FImage image, float[] v, int offset)` Sample the average response from each of the blocks in the image and insert into the vector.
`MBFImage`	`visualiseDescriptor(int height)` Compute the descriptor visualisation in the same form as the original matlab code.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_ORIENTATIONS_PER_SCALE
```
public static final int[] DEFAULT_ORIENTATIONS_PER_SCALE
```
    The default number of filter orientations per scale (from HF to LF)
  - DEFAULT_NUMBER_OF_BLOCKS
```
public static final int DEFAULT_NUMBER_OF_BLOCKS
```
    The default number spatial blocks
    
    See Also:
    
    Constant Field Values
  - DEFAULT_PREFILTER_FC
```
public static final int DEFAULT_PREFILTER_FC
```
    The default number of cycles per image for the pre-filter Gaussian
    
    See Also:
    
    Constant Field Values
  - DEFAULT_BOUNDARY_EXTENSION
```
public static final int DEFAULT_BOUNDARY_EXTENSION
```
    The default amount of padding to apply before convolving with the Gabor filters
    
    See Also:
    
    Constant Field Values
  - numberOfBlocks
```
public int numberOfBlocks
```
    The number of blocks in each direction
  - prefilterFC
```
public int prefilterFC
```
    The number of cycles per image for the pre-filter Gaussian
  - boundaryExtension
```
public int boundaryExtension
```
    The amount of padding to add before convolving with the Gabor functions
  - DEFAULT_SIZE
```
public static final int DEFAULT_SIZE
```
    Default image size (both height and width) for fixed size Gist
    
    See Also:
    
    Constant Field Values
  - gaborFilters
```
protected FImage[] gaborFilters
```
  - response
```
protected FloatFV response
```
  - orientationsPerScale
```
protected int[] orientationsPerScale
```
  - fixedSize
```
protected boolean fixedSize
```
  - imageWidth
```
protected int imageWidth
```
  - imageHeight
```
protected int imageHeight
```
- Constructor Detail
  - Gist
```
public Gist()
```
    Construct a fixed size Gist extractor using the default values.
  - Gist
```
public Gist(boolean fixedSize)
```
    Construct a variable or fixed size Gist extractor using the default values.
    
    Parameters:
    
    fixedSize - if true the images should be resized and cropped
  - Gist
```
public Gist(int width,
            int height)
```
    Construct a fixed-size Gist extractor, with the given image size and the default number of orientations per scale for the Gabor jet.
    
    Parameters:
    
    width - the image width
    
    height - the image height
  - Gist
```
public Gist(int width,
            int height,
            int[] orientationsPerScale)
```
    Construct a fixed-size Gist extractor, with the given image size and number of orientations per scale for the Gabor jet.
    
    Parameters:
    
    width - the image width
    
    height - the image height
    
    orientationsPerScale - the number of Gabor orientations per scale (from HF to LF)
  - Gist
```
public Gist(int[] orientationsPerScale,
            boolean fixedSize)
```
    Construct a variable or fixed size Gist extractor with the given number of orientations per scale for the Gabor jet.
    
    Parameters:
    
    orientationsPerScale - the number of Gabor orientations per scale (from HF to LF)
    
    fixedSize - if true the images should be resized and cropped
  - Gist
```
public Gist(int width,
            int height,
            int[] orientationsPerScale,
            boolean fixedSize)
```
    Construct a variable or fixed size Gist extractor with the given number of orientations per scale for the Gabor jet. The given height and width are ignored in variable size mode.
    
    Parameters:
    
    width - the image width
    
    height - the image height
    
    orientationsPerScale - the number of Gabor orientations per scale (from HF to LF)
    
    fixedSize - if true the images should be resized and cropped
  - Gist
```
protected Gist(int[] orientationsPerScale)
```
- Method Detail
  - analyseImage
```
public void analyseImage(IMAGE image)
```
    Description copied from interface: ImageAnalyser
    
    Analyse an image.
    
    Specified by:
    
    analyseImage in interface ImageAnalyser<IMAGE extends Image<?,IMAGE> & SinglebandImageProcessor.Processable<Float,FImage,IMAGE>>
    
    Parameters:
    
    image - The image to process in place.
  - extractGist
```
protected void extractGist(IMAGE image)
```
  - computeNumberOfSamplingBlocks
```
protected int computeNumberOfSamplingBlocks()
```
    Compute the number of sampling blocks that are used for every filter. The default implementation returns numberOfBlocks* numberOfBlocks, but can be overridden in combination with sampleResponses(FImage, float[], int) in a subclass to support different spatial sampling strategies.
    
    Returns:
    
    the number of sampling blocks per filter.
  - sampleResponses
```
protected void sampleResponses(FImage image,
                               float[] v,
                               int offset)
```
    Sample the average response from each of the blocks in the image and insert into the vector. This method could be overridden to support different spatial aggregation strategies (in which case computeNumberOfSamplingBlocks() should also be overridden).
    
    Parameters:
    
    image - the image to sample
    
    v - the vector to write into
    
    offset - the offset from which to sample
  - visualiseDescriptor
```
public MBFImage visualiseDescriptor(int height)
```
    Compute the descriptor visualisation in the same form as the original matlab code. The resultant image illustrates the dominant filter responses for each spatial bin. The filter scales are drawn with differing hues, and brightness is proportional to response value.
    
    Parameters:
    
    height - the desired height of the produced image
    
    Returns:
    
    the visualisation TODO: colour descriptors
  - getResponse
```
public FloatFV getResponse()
```
    Get the response vector from the previous call to analyseImage(Image).
    
    Returns:
    
    the response

Class Gist<IMAGE extends Image<?,IMAGE> & SinglebandImageProcessor.Processable<Float,FImage,IMAGE>>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_ORIENTATIONS_PER_SCALE

DEFAULT_NUMBER_OF_BLOCKS

DEFAULT_PREFILTER_FC

DEFAULT_BOUNDARY_EXTENSION

numberOfBlocks

prefilterFC

boundaryExtension

DEFAULT_SIZE

gaborFilters

response

orientationsPerScale

fixedSize

imageWidth

imageHeight

Constructor Detail

Gist

Gist

Gist

Gist

Gist

Gist

Gist

Method Detail

analyseImage

extractGist

computeNumberOfSamplingBlocks

sampleResponses

visualiseDescriptor

getResponse