source: branches/4.1/components/bio-formats/doc/reader-guide.txt @ 5727

Revision 5727, 8.3 KB checked in by melissa, 11 years ago (diff)

Updated documentation and what's new for today's release.

1            Bio-Formats File Format Reader Guide by Melissa Linkert
3This document is a brief guide to writing new Bio-Formats file format readers.
5All format readers should extend either loci.formats.FormatReader or a reader
8                              Methods to Override
9                             ---------------------
11boolean isThisType(byte[]) :
12  Check the first few bytes of a file to determine if the file can be read by
13  this reader.  You can assume that the first byte of the array corresponds to
14  the first byte of the file.  Return true if the file can be read; false if
15  not (or if there is no way of checking).
17String[] getSeriesUsedFiles() throws FormatException, IOException :
18  You only need to override this if your format uses multiple files in a single
19  dataset.  This method should return a list of all the files associated with
20  the given file name and the current series (i.e. every file needed to display
21  the current series).
22  For an example of how this works, see
23  It is recommended that the first line of this method be
24  "FormatTools.assertId(currentId, true, 1)" - this ensures that the file name
25  is non-null.
27byte[] openBytes(int, byte[], int, int, int, int) throws FormatException, IOException :
28  Returns a byte array containing the pixel data for a subimage specified
29  image from the given file.  The dimensions of the subimage (upper left X
30  coordinate, upper left Y coordinate, width, and height) are specified in the
31  final four int parameters.  This should throw a FormatException if the image
32  number is invalid (less than 0 or >= the number of images).  The ordering of
33  the array returned by openBytes should correspond to the values returned by
34  isLittleEndian() and isInterleaved().  Also, the length of the
35  byte array should be [image width * image height * bytes per pixel].  Extra
36  bytes will generally be truncated. It is recommended that the first line of
37  this method be "FormatTools.assertId(currentId, true, 1)" - this ensures that
38  the file name is non-null.
40protected void initFile(String) throws FormatException, IOException :
41  The majority of the file parsing logic should be placed in this method.  The
42  idea is to call this method once (and only once!) when the file is first
43  opened.  Generally, you will want to start by calling
44  super.initFile(String).  You will also need to set up the stream for reading
45  the file, as well as initializing any dimension information and metadata.
46  Most of this logic is up to you; however, you should populate the 'core'
47  variable (see loci.formats.CoreMetadata).
49  Note that each variable is initialized to 0 or null when
50  super.initFile(String) is called.
51  Also, super.initFile(String) constructs a Hashtable called "metadata" where
52  you should store any relevant metadata.
54Note that if the new format is a variant of a format currently supported by
55Bio-Formats, it is more efficient to make the new reader a subclass of the
56existing reader (rather than subclassing FormatReader).  In this case, it is
57usually sufficient to override initFile(String) and isThisType(byte[]).
59Every reader also has an instance of loci.formats.CoreMetadata.  All readers
60should populate the fields in CoreMetadata, which are essential to reading
61image planes.
63If you read from a file using something other than RandomAccessInputStream or
64Location, you *must* use the file name returned by Location.getMappedId(String),
65not the file name passed to the reader.
66Thus, a stub for initFile(String) might look like this:
68  protected void initFile(String id) throws FormatException, IOException {
69    super.initFile(id);
71    RandomAccessInputStream in = new RandomAccessInputStream(id);
72    // alternatively,
73    //FileInputStream in = new FileInputStream(Location.getMappedId(id));
75    // read basic file structure and metadata from stream
76  }
78For more details, see the javadoc for Location.mapId(String, String)
79and Location.getMappedId(String).
81                              Other Useful Things
82                             ---------------------
84- loci.common.RandomAccessInputStream is a hybrid RandomAccessFile/InputStream
85  class that is generally more efficient than either RandomAccessFile or
86  InputStream, and implements the DataInput interface.  It also keeps track
87  of open files, and will automatically close and re-open files as needed
88  to ensure that there aren't too many files open at one time.
89  It is recommended that you use this for reading binary files.
91- loci.formats.Location provides an API similar to, and supports
92  File-like operations on URLs.  It is highly recommended that you use this
93  instead of File.  See the javadoc for additional information.
95- loci.common.DataTools provides a number of methods for converting bytes to
96  shorts, ints, longs, etc.  It also supports reading most primitive types
97  directly from a RandomAccessInputStream (or other DataInput implementation).
99- loci.formats.ImageTools provides several methods for manipulating
100  primitive type arrays that represent images. Consult the source or javadoc
101  for more information.
103- If your reader relies on third-party code which may not be available to all
104  users, it is strongly suggested that you access this code only through a
105  loci.common.ReflectedUniverse object.  For an example of how this works,
106  see loci.formats.POITools.
108- Several common image compression types are supported through subclasses of
109  loci.formats.codec.BaseCodec.  These include JPEG, LZW, LZO, Base64, ZIP and
110  RLE (PackBits).
112- Debugging statements can be added using FormatHandler.debug(String).
114- If you wish to convert a file's metadata to OME-XML (strongly encouraged),
115  please see metadata-guide.txt further information.
117- Utility methods for reading and writing individual bits from a byte array
118  can be found in loci.formats.codec.BitBuffer and loci.formats.codec.BitWriter
120- Once you have written your file format reader, add a line to the readers.txt
121  file with the fully qualified name of the reader, followed by a '#' and the
122  file extensions associated with the file format. Note that ImageReader,
123  the master file format reader, tries to identify which format reader to use
124  according to the order given in readers.txt, so be sure to place your reader
125  in an appropriate position within the list.
127- The easiest way to test your new reader is by calling "java
128 <file name>".  If all goes well, you should see
129  all of the metadata and dimension information, along with a window showing
130  the images in the file.  ImageReader can take additional parameters; a
131  brief listing is provided for reference, but it is recommended that you
132  take a look at the contents of ConsoleTools.testRead to see exactly what
133  each one does.
135    Argument            Action
136    --------------------------
137    -nopix              Read metadata only; don't display images.
138    -nometa             Output only core metadata (dimension information).
139    -thumbs             Read thumbnails instead of regular images.
140    -merge              Combine separate channels into a set of RGB images.
141    -stitch             Open all files with a similar name.
142    -separate           Force RGB images to be split into separate channels.
143    -omexml             Output the OME-XML for the file.
144    -normalize          Normalize floating point images.
145    -fast               Display RGB images as quickly as possible.
146    -debug              Turn on debugging output.
147    -range              Specify a range of images to open.
148    -series             Set the series number (for container file formats).
149    -map                Specify file on disk to which name should be mapped.
151- If you wish to test using TestNG, loci.tests.testng.FormatReaderTest provides
152  several basic tests that work with all Bio-Formats readers.  See the
153  FormatReaderTest source code for additional information.
155- For more details, please look at the source code and javadocs.  Studying
156  existing readers is probably the best way to get a feel for the API; I would
157  recommend first looking at (this is the most
158  straightforward one). and InCellReader are also
159  good references that show off some of the nicer features of Bio-Formats.
161If you have questions about Bio-Formats, please contact:
162  Curtis Rueden <>
163  Melissa Linkert <>
Note: See TracBrowser for help on using the repository browser.