Changeset 6417


Ignore:
Timestamp:
05/28/10 15:19:24 (9 years ago)
Author:
curtis
Message:

Flesh out the IFormatReader javadoc a bit.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/components/bio-formats/src/loci/formats/IFormatReader.java

    r6301 r6417  
    6464  boolean isThisType(RandomAccessInputStream stream) throws IOException; 
    6565 
    66   /** Determines the number of images in the current file. */ 
     66  /** Determines the number of image planes in the current file. */ 
    6767  int getImageCount(); 
    6868 
    69   /** Checks if the images in the file are RGB. */ 
     69  /** 
     70   * Checks if the image planes in the file have more than one channel per 
     71   * {@link #openBytes} call. 
     72   * This method returns true if and only if {@link #getRGBChannelCount()} 
     73   * returns a value greater than 1. 
     74   */ 
    7075  boolean isRGB(); 
    7176 
     
    8792  /** 
    8893   * Gets the pixel type. 
    89    * @return the pixel type as an enumeration from <code>FormatTools</code> 
    90    * <i>static</i> pixel types such as <code>INT8</code>. 
     94   * @return the pixel type as an enumeration from {@link FormatTools} 
     95   * <i>static</i> pixel types such as {@link FormatTools#INT8}. 
    9196   */ 
    9297  int getPixelType(); 
    9398 
    9499  /** 
    95    * Gets the number of valid bits per pixel.  The number of valid bits per 
     100   * Gets the number of valid bits per pixel. The number of valid bits per 
    96101   * pixel is always less than or equal to the number of bits per pixel 
    97102   * that correspond to {@link #getPixelType()}. 
     
    106111  int getEffectiveSizeC(); 
    107112 
    108   /** Gets the number of channels per RGB image (if not RGB, this returns 1). */ 
     113  /** 
     114   * Gets the number of channels returned with each call to openBytes. 
     115   * The most common case where this value is greater than 1 is for interleaved 
     116   * RGB data, such as a 24-bit color image plane. However, it is possible for 
     117   * this value to be greater than 1 for non-interleaved data, such as an RGB 
     118   * TIFF with Planar rather than Chunky configuration. 
     119   */ 
    109120  int getRGBChannelCount(); 
    110121 
    111   /** Gets whether the images are indexed color. */ 
     122  /** 
     123   * Gets whether the image planes are indexed color. 
     124   * This value has no impact on {@link #getSizeC()}, 
     125   * {@link #getEffectiveSizeC()} or {@link #getRGBChannelCount()}. 
     126   */ 
    112127  boolean isIndexed(); 
    113128 
    114129  /** 
    115    * Returns false if isIndexed is false, or if isIndexed is true and the lookup 
    116    * table represents "real" color data.  Returns true if isIndexed is true 
    117    * and the lookup table is only present to aid in visualization. 
     130   * Returns false if {@link #isIndexed()} is false, or if {@link #isIndexed()} 
     131   * is true and the lookup table represents "real" color data. Returns true 
     132   * if {@link #isIndexed} is true and the lookup table is only present to aid 
     133   * in visualization. 
    118134   */ 
    119135  boolean isFalseColor(); 
     
    122138   * Gets the 8-bit color lookup table associated with 
    123139   * the most recently opened image. 
    124    * If no images have been opened, or if isIndexed() returns false, then 
    125    * this returns null.  Also, if getPixelType() returns anything other than 
    126    * <code>INT8</code> or <code>UINT8</code>, this method will return null. 
     140   * If no image planes have been opened, or if {@link #isIndexed()} returns 
     141   * false, then this may return null. Also, if {@link #getPixelType()} returns 
     142   * anything other than {@link FormatTools#INT8} or {@link FormatTools#UINT8}, 
     143   * this method will return null. 
    127144   */ 
    128145  byte[][] get8BitLookupTable() throws FormatException, IOException; 
     
    131148   * Gets the 16-bit color lookup table associated with 
    132149   * the most recently opened image. 
    133    * If no images have been opened, or if isIndexed() returns false, then 
    134    * this returns null.  Also, if getPixelType() returns anything other than 
    135    * <code>INT16</code> or <code>UINT16</code>, this method will return null. 
     150   * If no image planes have been opened, or if {@link #isIndexed()} returns 
     151   * false, then this may return null. Also, if {@link #getPixelType()} returns 
     152   * anything other than {@link FormatTools#INT16} or {@link 
     153   * FormatTools#UINT16}, this method will return null. 
    136154   */ 
    137155  short[][] get16BitLookupTable() throws FormatException, IOException; 
     
    139157  /** 
    140158   * Gets the lengths of each subdimension of C, 
    141    * in fastest-to-sloweset rasterization order. 
     159   * in fastest-to-slowest rasterization order. 
    142160   */ 
    143161  int[] getChannelDimLengths(); 
     
    189207   * Gets whether or not the channels are interleaved. This method exists 
    190208   * because X and Y must appear first in the dimension order. For 
    191    * interleaved data, XYCTZ or XYCZT is used, and this method returns true. 
     209   * interleaved data, {@link #getDimensionOrder()} returns XYCTZ or XYCZT, 
     210   * and this method returns true. 
    192211   */ 
    193212  boolean isInterleaved(); 
     
    204223  /** 
    205224   * Obtains the specified image plane from the current file as a byte array. 
     225   * @see openBytes(int, byte[]) 
    206226   */ 
    207227  byte[] openBytes(int no) throws FormatException, IOException; 
     
    216236  /** 
    217237   * Obtains the specified image plane from the current file into a 
    218    * pre-allocated byte array of (sizeX * sizeY * bytesPerPixel * RGB channel 
    219    * count). 
     238   * pre-allocated byte array of 
     239   * (sizeX * sizeY * bytesPerPixel * RGB channel count). 
    220240   * 
    221241   * @param no the image index within the file. 
     
    290310 
    291311  /** 
    292    * Specifies whether or not to collect metadata. 
    293    * @deprecated Use {@link setMetadataOptions(MetadataOptions)} instead. 
    294    */ 
    295   void setMetadataCollected(boolean collect); 
    296  
    297   /** 
    298    * Returns true if we should collect metadata. 
    299    * @deprecated Use {@link getMetadataOptions()} instead. 
    300    */ 
    301   boolean isMetadataCollected(); 
    302  
    303   /** 
    304312   * Specifies whether or not to save proprietary metadata 
    305313   * in the MetadataStore. 
     
    398406 
    399407  /** 
    400    * Returns a hashtable containing the union of all of the field/value pairs 
    401    * in getGlobalMetadata() and getSeriesMetadata().  The series name is 
    402    * prepended to fields in the getSeriesMetadata() hashtable. 
    403    * 
    404    * @deprecated Use getGlobalMetadata() or getSeriesMetadata() instead. 
    405    */ 
    406   Hashtable<String, Object> getMetadata(); 
    407  
    408   /** 
    409408   * Obtains the hashtable containing metadata field/value pairs from the 
    410409   * current series in the current file. 
     
    450449 
    451450  /** 
    452    * Retrieves all underlying readers.  Returns null if there are no underlying 
    453    * readers. 
     451   * Retrieves all underlying readers. 
     452   * Returns null if there are no underlying readers. 
    454453   */ 
    455454  IFormatReader[] getUnderlyingReaders(); 
    456455 
    457   /** 
    458    * Returns true if this is a single-file format. 
    459    */ 
     456  /** Returns true if this is a single-file format. */ 
    460457  boolean isSingleFile(String id) throws FormatException, IOException; 
    461458 
     
    466463  boolean hasCompanionFiles(); 
    467464 
     465  // -- Deprecated methods -- 
     466 
     467  /** 
     468   * Specifies whether or not to collect metadata. 
     469   * @deprecated Use {@link #setMetadataOptions(MetadataOptions)} instead. 
     470   */ 
     471  void setMetadataCollected(boolean collect); 
     472 
     473  /** 
     474   * Returns true if we should collect metadata. 
     475   * @deprecated Use {@link #getMetadataOptions()} instead. 
     476   */ 
     477  boolean isMetadataCollected(); 
     478 
     479  /** 
     480   * Returns a hashtable containing the union of all of the field/value pairs 
     481   * in getGlobalMetadata() and getSeriesMetadata(). The series name is 
     482   * prepended to fields in the getSeriesMetadata() hashtable. 
     483   * 
     484   * @deprecated Use #getGlobalMetadata() or #getSeriesMetadata() instead. 
     485   */ 
     486  Hashtable<String, Object> getMetadata(); 
     487 
    468488} 
Note: See TracChangeset for help on using the changeset viewer.