Retina 0.1.0-SNAPSHOT API documentation

*Chakrabarti2011-file-list*

This variable lists all the files that were found in the Chakrabarti2011 database (Aug 2013)

*Foster2004-file-list*

This variable lists all the files that were found in the Foster2004 database (Aug 2013)

*Parragas1998-file-list*

This variable lists all the files that were found in the Parragas1998 database (Aug 2013)

JMatIO-reader

Yields a jmatio MatFileReader (com.jmatio.io.MatFileReader) object for the given file.  This
may throw an exception if (a) the file is not found, (b) there was a read error, ie, the file
is not a proper Matlab v5 compatible file, or (c) the jmatio library cannot be loaded.  In the
latter case, the library may be loaded dynamically using jmatio-load.  The file argument may be
a (string) filename or a File object.

autobuild-hyperspectral-cache

See build-hyperspectral-cache.  Give then locations of the hyperspectral image databases, builds
a hyperspectral image cache from all images.

build-hyperspectral-cache

macro

Used to build hyperspectral image caches.  The body is executed such that any call to the
push-to-cache function will insert the image into the cache.  After body has been executed, the
cache is closed and the filename returned.  On error, an exception is thrown.  The file argument
may be may be a string or a File object.

calculate-hyperspectral-cache-statistics

(calculate-hyperspectral-cache-statistics h max) yields a seq of seqs; each element of the outer
  seq is a single distance/wavelength-difference pair represented by a seq of [distance
  absolute-difference-in-wavelength correlation]. Distances out to a maximum distance of
  sqrt(2)*max are calculated (ie, a distance of max rows and max columns away).
(calculate-hyperspectral-cache-statistics h) is equivalent to
  (calculate-hyperspectral-cache-statistics h 20).

count-patches-in-cache

Yields the total number of image caches of size patch-width by patch-height in the hyperspectral
image cache given.  The cache must be a map, as returned by read-hyperspectral-cache.

count-patches-in-image

Yields the number of patches of size patch-height x patch-width in a height x width image

draw-patches

Yields a lazy sequence of image patches drawn from the given hyperspectral cache map, which must
be created by read-hyperspectral-cache.  The seq will contain n image patches of size patch-width
by patch-height sampled randomly from the database such that the first several patches come from
the first image, the next several from the next image, etc.  The number of patches drawn from
each is based on the fraction of possible patches that can be drawn from that image.  The
optional argument :random-seed may be given to force a particular random seed.  If n is nil then
all patches are returned.

hyperspectral-file-list

Yields a list of files given the database locations.  For any database not given, those files are
not included (but an empty string "" or a period "." may be used to indicate the current
directory).  File objects are returned in a single lazy seq; only those files that exist are
returned, unless :strings is true, in which case string objects are returned.
Note that for the Parragas1998 database, the "brelstaff" directory containing the image folders
is the expected argument.  For the Chakrabarti2011 database, CZ_hsdb directory is expected.  For
Foster2004, the directory containing the "scene1", "scene2" etc. directories is expected.

hyperspectral-image

Yields a hyperspectral-image structure given the hyperspectral image data specified in the
options.  This hyperspectral-image structure can be understood by push-to-cache and
build-hyperspectral-cache.  The arguments to this function must be as follows:
image-fn must be a function that, given two integers, returns the pixel (a seq of numbers) at
 those coordinates
size must be the [rows cols] of the image
:filter may be a sequence of either masks indicating which bits should be excluded (all cells
 set to nil, false, or 0 will be excluded), rectangular regions to be excluded, specified
 by [[row-ul col-ul] [row-lr col-lr]] where ul and lr stand for upper-left and lower-right, or a
 function that takes a row and col as arguments and returns true for any pixel to be included.
:wavelengths is by default equivalent to (range 400 721 10) and specifies the wavelengths on
 which the image is sampled.

hyperspectral-to-RGB

Yields an BufferedImage object containing the RGB matrix converted from the given hyperspectral
image.  This function uses CIE-xyz1931-matrix for conversion, which was originally obtained from
the psychtoolbox.

images-from-cache

Yields a lazy seq of the hyperspectral images in the cache (read by read-hyperspectral-cache).
An optional :delay may be set to true if delay objects are prefered (ie, if not all images will
be used, then the unused images will not be loaded).

load-JMatIO

Loads the JMatIO class and returns true if successful.  This function throws exceptions on
error due to not wrapping a try statement around the ClassLoader and Class.forName calls.
The path argument may be a File, String, or URL.  If the path is a string, it is assumed to be
a file unless it begins with "http://".  If the JMatIO library is already loaded, this
returns nil.

patch-fn-from-image

Yields a function that, given an index i, yields the ith image patch of size patch-height x
patch-width from the given image.  The index i should begin at 0.  The image should be either
an HSImage instance or a data structure that can handle nth.

push-to-cache

Pushes the given image, absent all exclusions, to the open hyperspectral cache.  This function
can be called only from within a build-hyperspectral-cache form.  Exclusions may be specified as
matrices of booleans (or numbers where 0/false/nil are taken to be included), or as seqs of
rectangles specified as [[row-ul col-ul] [row-lr col-lr]] where ul and lr indicate upper left and
lower right, respectively (rectangles are assumed to be inclusive).

read-Chakrabarti2011-image

Yields the hyperspectral image structure for the hyperspectral image specified by file. File may
be a string or a File object.  If errors are encountered, exceptions are thrown.  All given
filters are included in the hyperspectral image definition, along with the exclusions included
in the Chakrabarti2011 matlab file.  If you do not wish to exclude the lbl field of the matlab
file, then the option :filter-lbl should be false.  The contents of the calib.txt file can also
be passed in the :calib argument; otherwise it is loaded automatically.

read-Foster2004-image

Yields the hyperspectral image structure for the hyperspectral image specified by file. File may
be a string or a File object.  If errors are encountered, exceptions are thrown.  All given
filters are included in the hyperspectral image definition.

read-Parragas1998-image

Yields the hyperspectral image structure for the hyperspectral image specified by directory. The
directory argument may be a string or a File object.  If errors are encountered, exceptions are
thrown.  All given filters are included in the hyperspectral image definition.

read-hyperspectral-cache

Opens the given file (either a File objerct or a filename) and reads in each hyperspectral image
in the cache sequentially and lazilly.  Note that in order to ensure that the file is closed,
the sequence must be entirely evaluated or the .close method must be called on the :stream field
of the returned map.  The returned map contains three fields: :stream (the file), :index (the
sizes of all images contained in this cache), and :images (the lazy sequence of images).

read-matlab-file

Yields a map of variable name to the MLArray object saved to that name in the given MAT file.
The given file may be either a File object or a string.  If JMatIO is not loaded, an exception
will be thrown.

use-png-as-hyperspectral-mask

Given a hyerspectral image and the filename, file object, or BufferedImage object for a PNG file,
uses the png file as a mask, where the :exclude-color option (default 0/black) is used as a clue
that the hyperspectral pixel will be excluded, and yields a version of hsimage that is suitable
for use with push-to-cache with the proper exclusions. Note that the images must be the same size
or an error is thrown.

write-hyperspectral-as-png

Writes a .png file to the given file location by converting the given hyperspectral image to
an RGB image using hyperspectral-to-RGB.  Yields the java.io.File object if successful and nil
otherwise.