Changeset 2588


Ignore:
Timestamp:
04/10/07 11:40:47 (13 years ago)
Author:
melissa
Message:

Updated documentation to reflect recent API changes.

Location:
trunk/loci/formats
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/loci/formats/reader-guide.txt

    r2568 r2588  
    1515  not (or if there is no way of checking). 
    1616 
    17 int getImageCount(String) throws FormatException, IOException : 
    18   Return the number of image planes in the file.  This method should begin 
    19   by checking if the given argument is equal to the current file; if not, 
    20   initFile(String) should be called (see below). 
     17int getImageCount() throws FormatException, IOException : 
     18  Return the number of image planes in the file.   
    2119 
    22 boolean isRGB(String) throws FormatException, IOException : 
     20boolean isRGB() throws FormatException, IOException : 
    2321  This should only return true if the file's image planes are stored as RGB 
    24   or indexed color.  All other cases return false.  This method should begin 
    25   by checking if the given argument is equal to the current file; if not, 
    26   initFile(String) should be called (see below). 
     22  or indexed color.  All other cases return false.  
    2723 
    28 boolean isLittleEndian(String) throws FormatException, IOException : 
     24boolean isLittleEndian() throws FormatException, IOException : 
    2925  Return the byte ordering of the pixel data.  Note that in some cases, this 
    3026  is different from the file's native ordering.  If the pixel data is 
    3127  guaranteed to have 8 bits per pixel, then isLittleEndian can return 
    32   anything. This method should begin by checking if the given argument is equal 
    33   to the current file; if not, initFile(String) should be called (see below). 
     28  anything. 
    3429 
    35 boolean isInterleaved(String) throws FormatException, IOException : 
     30boolean isInterleaved() throws FormatException, IOException : 
    3631  This is only relevant if the file's image planes are stored as RGB or 
    3732  indexed color; however, it should always be implemented.  If the image 
    3833  planes are RGB, and the pixel data is stored as "RRR...GGG...BBB", then 
    3934  return false.  Otherwise, if the pixel data is stored as "RGBRGBRGB..." 
    40   return true.  This method should begin by checking if the given argument 
    41   is equal to the current file; if not, initFile(String) should be called 
    42   (see below). 
     35  return true. 
    4336 
    44 String[] getUsedFiles(String) throws FormatException, IOException : 
     37String[] getUsedFiles() throws FormatException, IOException : 
    4538  You only need to override this if your format uses multiple files in a single 
    4639  dataset.  This method should return a list of all the files associated with 
     
    4841  For an example of how this works, see loci.formats.in.PerkinElmerReader. 
    4942 
    50 byte[] openBytes(String, int) throws FormatException, IOException : 
     43byte[] openBytes(int) throws FormatException, IOException : 
    5144  Returns a byte array containing the pixel data for the specified image from 
    5245  the given file.  Should throw a FormatException if the image number is invalid 
    5346  (less than 0 or >= the number of images).  The ordering of the array 
    5447  returned by openBytes should correspond to the values returned by 
    55   isLittleEndian(String) and isInterleaved(String).  Also, the length of the 
     48  isLittleEndian() and isInterleaved().  Also, the length of the 
    5649  byte array should be [image width * image height * bytes per pixel].  Extra 
    57   bytes will generally be truncated.  This method should begin 
    58   by checking if the given argument is equal to the current file; if not, 
    59   initFile(String) should be called (see below). 
     50  bytes will generally be truncated. 
    6051 
    61 BufferedImage openImage(String, int) throws FormatException, IOException : 
     52BufferedImage openImage(int) throws FormatException, IOException : 
    6253  Basically the same as openBytes, but returns a java.awt.image.BufferedImage 
    6354  instead of a byte array.  In general, the easiest way to implement this is 
     
    8475  super.initFile(String).  You will also need to set up the stream for reading 
    8576  the file, as well as initializing any dimension information and metadata. 
    86   Most of this logic is up to you; however, it is wise to set the following 
    87   variables: 
    88     int sizeX[0] : the image width 
    89     int sizeY[0] : the image height 
    90     int sizeZ[0] : number of planes along Z axis (set to 1 if there are none) 
    91     int sizeC[0] : the number of channels (set to 3 if RGB/indexed color) 
    92     int sizeT[0] : number of planes along T axis (set to 1 if there are none) 
    93     String currentOrder[0] : the dimension ordering of the planes 
    94     int pixelType[0] : corresponds to the number of bytes per pixel; see 
    95                        constant values in FormatReader for a list of valid 
    96                        values 
    97     boolean orderCertain[0] : set to true if you are certain that the dimension 
    98                               order is correct 
     77  Most of this logic is up to you; however, you should populate the 'core' 
     78  variable (see loci.formats.CoreMetadata). 
    9979 
    10080  Note that each variable is initialized to 0 or null when 
     
    167147  loci.formats.MetadataStore (every subclass of FormatReader keeps an instance 
    168148  of MetadataStore by default); so to add OME-XML support is as simple as 
    169   calling getMetadataStore(String) on a format reader instance, and then 
     149  calling getMetadataStore() on a format reader instance, and then 
    170150  calling the appropriate "set" methods as documented in OMEXMLMetadataStore. 
    171151 
  • trunk/loci/formats/using-bioformats.txt

    r2568 r2588  
    2727the appropriate reader. 
    2828 
     29Prior to retrieving pixels or metadata, it is necessary to call setId(String) 
     30on the reader instance, passing in the name of the file to read. 
     31 
    2932Raw pixels are always retrieved one plane at a time.  Planes can be returned 
    3033either in a byte array, or in a java.awt.image.BufferedImage (using 
    31 openBytes(String, int) and openImage(String, int) respectively).  It is entirely 
     34openBytes(int) and openImage(int) respectively).  It is entirely 
    3235up to you which method to use, as the pixel values are always identical. 
    3336In general, BufferedImages are more convenient for viewer applications and 
     
    3942appropriate accessor method in parentheses: 
    4043 
    41 - image width (getSizeX(String)) 
    42 - image height (getSizeY(String)) 
    43 - total number of images per file (getImageCount(String)) 
    44 - number of slices per file (getSizeZ(String)) 
    45 - number of timepoints per file (getSizeT(String)) 
    46 - number of actual channels per file (getSizeC(String)) 
    47 - number of channels per image (getRGBChannelCount(String)) 
    48 - the ordering of the images within the file (getDimensionOrder(String)) 
    49 - whether each image is RGB (isRGB(String)) 
    50 - whether the pixel bytes in little-endian order (isLittleEndian(String)) 
    51 - whether the channels in an image are interleaved (isInterleaved(String)) 
    52 - the type of pixel data in this file (getPixelType(String)) 
     44- image width (getSizeX()) 
     45- image height (getSizeY()) 
     46- total number of images per file (getImageCount()) 
     47- number of slices per file (getSizeZ()) 
     48- number of timepoints per file (getSizeT()) 
     49- number of actual channels per file (getSizeC()) 
     50- number of channels per image (getRGBChannelCount()) 
     51- the ordering of the images within the file (getDimensionOrder()) 
     52- whether each image is RGB (isRGB()) 
     53- whether the pixel bytes in little-endian order (isLittleEndian()) 
     54- whether the channels in an image are interleaved (isInterleaved()) 
     55- the type of pixel data in this file (getPixelType()) 
    5356 
    5457All file formats are guaranteed to accurately report core metadata. 
     
    5861is stored internally in a java.util.Hashtable, and can be accessed in one of 
    5962two ways: individual values can be retrieved by calling 
    60 getMetadataValue(String, String), which gets the value of the specified key. 
    61 Alternatively, getMetadata(String) will return the entire Hashtable. 
     63getMetadataValue(String), which gets the value of the specified key. 
     64Alternatively, getMetadata() will return the entire Hashtable. 
    6265Note that the keys in this Hashtable are different for each format, hence the 
    6366name "format-specific metadata". 
     
    109112file. 
    110113 
    111 A word of warning: IFormatWriter.save(String, Image, boolean) accepts generic 
    112 java.awt.Images, and converts them to a BufferedImage under the hood. 
     114A word of warning: IFormatWriter.saveImage(String, Image, boolean) accepts  
     115generic java.awt.Images, and converts them to a BufferedImage under the hood. 
    113116The problem is that not all formats support all types of data (e.g. JPEG 
    114117does not support 16-bit data).  To prevent the possibility of corrupt or 
    115 invalid files, it is important to check that the Image you supply to save() 
     118invalid files, it is important to check that the Image you supply to saveImage() 
    116119is supported.  This can be done using the isSupportedType and getPixelTypes 
    117120methods of IFormatWriter. 
     
    165168  result is a hybrid class that extends InputStream and implements DataInput to 
    166169  meet all of our goals. 
     170 
     171o RLE-compressed QuickTime movies will look funny if the planes are not read 
     172  in sequential order. 
  • trunk/loci/formats/whats-new.txt

    r2467 r2588  
     1* Added API to toggle metadata collection 
     2* Deprecated methods in IFormatReader that accept the 'id' parameter 
     3* Deprecated IFormatWriter.save in favor of IFormatWriter.saveImage 
     4* Removed "ignore color table" logic - replaced with Leica-specific solution 
     5* Moved dimension swapping and min/max calculation logic to delegates. 
     6* Miscellaneous bugfixes/tweaks in most readers 
     7 
    182007 Mar 16: 
    29* Fixed calibration bugs in importer plugin 
Note: See TracChangeset for help on using the changeset viewer.