Changeset 2319


Ignore:
Timestamp:
02/22/07 16:56:17 (13 years ago)
Author:
curtis
Message:

Some documentation updates.

Location:
trunk/loci/formats
Files:
1 deleted
5 edited
1 moved

Legend:

Unmodified
Added
Removed
  • trunk/loci/formats/lgpl.txt

    r835 r2319  
    134134writing it).  Whether that is true depends on what the Library does 
    135135and what the program that uses the Library does. 
    136    
     136 
    137137  1. You may copy and distribute verbatim copies of the Library's 
    138138complete source code as you receive it, in any medium, provided that 
  • trunk/loci/formats/reader-guide.txt

    r2292 r2319  
    1               Bio-Formats Getting Started Guide by Melissa Linkert 
     1            Bio-Formats File Format Reader Guide by Melissa Linkert 
    22 
    33This document is a brief guide to writing new Bio-Formats file format readers. 
     
    88---=== Methods to override ===--- 
    99 
    10 boolean isThisType(byte[]) :  
     10boolean isThisType(byte[]) : 
    1111  Check the first few bytes of a file to determine if the file can be read by 
    1212  this reader.  You can assume that the first byte of the array corresponds to 
     
    2929  is different from the file's native ordering.  If the pixel data is 
    3030  guaranteed to have 8 bits per pixel, then isLittleEndian can return 
    31   anything. This method should begin by checking if the given argument is equal  
     31  anything. This method should begin by checking if the given argument is equal 
    3232  to the current file; if not, initFile(String) should be called (see below). 
    3333 
     
    3737  planes are RGB, and the pixel data is stored as "RRR...GGG...BBB", then 
    3838  return false.  Otherwise, if the pixel data is stored as "RGBRGBRGB..." 
    39   return true.  This method should begin by checking if the given argument  
    40   is equal to the current file; if not, initFile(String) should be called  
     39  return true.  This method should begin by checking if the given argument 
     40  is equal to the current file; if not, initFile(String) should be called 
    4141  (see below). 
    4242 
     
    105105    int sizeT[0] : number of planes along T axis (set to 1 if there are none) 
    106106    String currentOrder[0] : the dimension ordering of the planes 
    107     int pixelType[0] : corresponds to the number of bytes per pixel; see  
     107    int pixelType[0] : corresponds to the number of bytes per pixel; see 
    108108                       constant values in FormatReader for a list of valid 
    109109                       values 
     
    133133  protected void initFile(String id) throws FormatException, IOException { 
    134134    super.initFile(id); 
    135      
     135 
    136136    RandomAccessStream in = new RandomAccessStream(id); 
    137137    // alternatively, 
     
    153153  It is recommended that you use this for reading binary files. 
    154154 
    155 - loci.formats.Location provides an API similar to java.io.File, and supports  
    156   File-like operations on URLs.  It is highly recommended that you use this  
     155- loci.formats.Location provides an API similar to java.io.File, and supports 
     156  File-like operations on URLs.  It is highly recommended that you use this 
    157157  instead of File.  See the javadoc for additional information. 
    158158 
     
    167167  information. 
    168168 
    169 - If your reader relies on third-party code which may not be available to all  
     169- If your reader relies on third-party code which may not be available to all 
    170170  users, it is strongly suggested that you access this code only through a 
    171171  loci.formats.ReflectedUniverse object.  For an example of how this works, 
     
    173173 
    174174- Several common image compression types are supported through subclasses of 
    175   loci.formats.BaseCompressor.  These include LZW, LZO, Base64, ZIP and  
     175  loci.formats.BaseCompressor.  These include LZW, LZO, Base64, ZIP and 
    176176  RLE (PackBits). 
    177177 
     
    180180- If you wish to convert a file's metadata to OME-XML (strongly encouraged), 
    181181  loci.formats.OMEXMLMetadataStore provides methods for creating OME-XML from 
    182   metadata values.  Note that OMEXMLMetadataStore is a subclass of  
     182  metadata values.  Note that OMEXMLMetadataStore is a subclass of 
    183183  loci.formats.MetadataStore (every subclass of FormatReader keeps an instance 
    184184  of MetadataStore by default); so to add OME-XML support is as simple as 
  • trunk/loci/formats/readers.txt

    r2275 r2319  
    44 
    55# LOCI Bio-Formats package for reading and converting biological file formats. 
    6 # Copyright (C) 2005-@year@ Melissa Linkert, Curtis Rueden, Chris Allan 
    7 # and Eric Kjellman. 
     6# Copyright (C) 2005-@year@ Melissa Linkert, Curtis Rueden, Chris Allan, 
     7# Eric Kjellman and Brian Loranger. 
    88# 
    99# This program is free software; you can redistribute it and/or modify 
     
    2020# along with this program; if not, write to the Free Software 
    2121# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
     22 
     23# This document is a configuration file identifying all file format readers 
     24# available to Bio-Formats, and the order in which they should be used. 
     25# Please do not edit unless you know what you are doing (see reader-guide.txt). 
    2226 
    2327# javax.imageio readers 
  • trunk/loci/formats/using-bioformats.txt

    r2311 r2319  
    33 
    44This document describes various things that are useful to know when working 
    5 with Bio-Formats.  It is recommended that you obtain the Bio-Formats source  
     5with Bio-Formats.  It is recommended that you obtain the Bio-Formats source 
    66by following the directions at http://www.loci.wisc.edu/software, rather than 
    77using an official release.  It is also recommended that you have a copy of the 
     
    1212http://www.loci.wisc.edu/ome/formats.html 
    1313 
    14  
    15                               Basic File Reading  
     14                              Basic File Reading 
    1615                         --------------------------- 
    1716 
     
    2726 
    2827Raw pixels are always retrieved one plane at a time.  Planes can be returned 
    29 either in a byte array, or in a java.awt.image.BufferedImage (using  
     28either in a byte array, or in a java.awt.image.BufferedImage (using 
    3029openBytes(String, int) and openImage(String, int) respectively).  It is entirely 
    3130up to you which method to use, as the pixel values are always identical. 
    32 In general, BufferedImages are more convenient for viewer applications and  
     31In general, BufferedImages are more convenient for viewer applications and 
    3332applications that don't need to perform computations on pixel data, while byte 
    3433arrays are better for applications that perform pixel manipulations. 
     
    4645- number of channels per image (getRGBChannelCount(String)) 
    4746- the ordering of the images within the file (getDimensionOrder(String)) 
    48 - whether or not each image is RGB (isRGB(String)) 
    49 - whether or not the pixel bytes in little-endian order (isLittleEndian(String)) 
    50 - whether or not the channels in an image are interleaved (isInterleaved(String)) 
     47- whether each image is RGB (isRGB(String)) 
     48- whether the pixel bytes in little-endian order (isLittleEndian(String)) 
     49- whether the channels in an image are interleaved (isInterleaved(String)) 
    5150- the type of pixel data in this file (getPixelType(String)) 
    5251 
     
    5554Format-specific metadata refers to any other data specified in the file - this 
    5655includes acquisition and hardware parameters, among other things.  This data 
    57 is stored internally in a java.util.Hashtable, and can be accessed in one of  
    58 two ways: individual values can be retrieved by calling  
    59 getMetadataValue(String, String), which gets the value of the specified key.   
     56is stored internally in a java.util.Hashtable, and can be accessed in one of 
     57two ways: individual values can be retrieved by calling 
     58getMetadataValue(String, String), which gets the value of the specified key. 
    6059Alternatively, getMetadata(String) will return the entire Hashtable. 
    6160Note that the keys in this Hashtable are different for each format, hence the 
     
    6564                           ---------------------- 
    6665 
    67 The previous section described how to read pixels as they are stored in the  
    68 file.  However, the native format isn't necessarily convenient, so Bio-Formats  
     66The previous section described how to read pixels as they are stored in the 
     67file.  However, the native format isn't necessarily convenient, so Bio-Formats 
    6968provides a few extras to make file reading more flexible. 
    7069 
     
    9594We are planning support for OME-XML in the near future. 
    9695 
    97 The writer API (see loci.formats.IFormatWriter) is very similar to the reader  
     96The writer API (see loci.formats.IFormatWriter) is very similar to the reader 
    9897API, in that files are written one plane at time (rather than all at once). 
    9998 
     
    107106java.awt.Images, and converts them to a BufferedImage under the hood. 
    108107The problem is that not all formats support all types of data (e.g. JPEG 
    109 does not support 16-bit data).  To prevent the possibility of corrupt or  
     108does not support 16-bit data).  To prevent the possibility of corrupt or 
    110109invalid files, it is important to check that the Image you supply to save() 
    111110is supported.  This can be done using the isSupportedType and getPixelTypes 
     
    114113Please see the Movie Stitcher (loci.apps.stitcher) for an example of how 
    115114to write files using Bio-Formats. 
    116  
    117115 
    118116                    Arcane Notes and Implementation Details 
     
    124122  BufferedImage, the IFormatWriter API only accepts a java.awt.Image. 
    125123  For completeness, we should add a method to IFormatWriter that accepts an 
    126   array of bytes for writing.  The only reason for not doing so is that no   
    127   one has needed this feature (yet).  If you think this would be useful,  
     124  array of bytes for writing.  The only reason for not doing so is that no 
     125  one has needed this feature (yet).  If you think this would be useful, 
    128126  it can be added. 
    129127 
    130 o IFormatWriter accepts Image objects, and not BufferedImages; yet all writers  
     128o IFormatWriter accepts Image objects, and not BufferedImages; yet all writers 
    131129  convert the Image to a BufferedImage.  You can still pass in a 
    132130  BufferedImage, but you are free to pass in any Image object (this is mainly 
     
    136134  array, but there is no corresponding method for openImage.  The 
    137135  rationale behind pre-allocated byte arrays is (1) array allocation takes 
    138   a relatively long time; and (2) supposedly pre-allocation saves memory. 
    139   The reason there isn't something similar for openImage (i.e. a method that 
    140   takes a pre-allocated BufferedImage) is that it's kind of a pain to implement, 
    141   and no one has cared so far.  If you want this method, we can work towards 
    142   adding it. 
     136  a relatively long time; and (2) pre-allocation avoids memory spikes on the 
     137  heap.  The reason there isn't something similar for openImage (i.e., a method 
     138  that takes a pre-allocated BufferedImage) is that it's kind of a pain to 
     139  implement, and no one has cared so far.  If you want this method, we can work 
     140  towards adding it. 
    143141 
    144 o Leica LEI files sometimes (actually, frequently) don't look right.   
     142o Leica LEI files sometimes (actually, frequently) don't look right. 
    145143  However, there is a sneaky way of getting Bio-Formats to read them correctly: 
    146   call setColorTableIgnored(true) on the reader object.  Why?  Well, the LEI  
    147   file format consists of a "header" file (.lei extension), and a set of TIFF  
    148   files (which contain the actual pixel data).  The LEI acquisition software  
    149   allows the user to specify an "acquisition channel" - in fact, multiple  
    150   acquisition channels can be specified for each dataset.  Then for each  
    151   acquistion channel, a color lookup table is applied to the grayscale data.   
    152   This doesn't sound so bad, but it gets really ugly if half of the TIFF files  
    153   in a dataset had an acquisition channel specified, and half didn't - you get  
    154   alternating RGB and grayscale planes.  Forcing Bio-Formats to ignore the  
    155   color tables means you get all grayscale planes, but the number of channels  
     144  call setColorTableIgnored(true) on the reader object.  Why?  Well, the LEI 
     145  file format consists of a "header" file (.lei extension), and a set of TIFF 
     146  files (which contain the actual pixel data).  The LEI acquisition software 
     147  allows the user to specify an "acquisition channel" - in fact, multiple 
     148  acquisition channels can be specified for each dataset.  Then for each 
     149  acquisition channel, a color lookup table is applied to the grayscale data. 
     150  This doesn't sound so bad, but it gets really ugly if half of the TIFF files 
     151  in a dataset had an acquisition channel specified, and half didn't - you get 
     152  alternating RGB and grayscale planes.  Forcing Bio-Formats to ignore the 
     153  color tables means you get all grayscale planes, but the number of channels 
    156154  is preserved (so channel merging still works). 
    157155 
    158 o Importing multi-file formats (Leica LEI, PerkinElmer, FV1000 OIF, ICS, and  
     156o Importing multi-file formats (Leica LEI, PerkinElmer, FV1000 OIF, ICS, and 
    159157  Prairie TIFF) can fail if any of the files are renamed.  There are 
    160158  "best guess" heuristics in these readers, but they aren't guaranteed to work 
     
    168166  open file descriptors (in the current JVM).  Currently, the maximum is 200, 
    169167  which is lower than the default on most systems.  Side note on I/O: the 
    170   reasoning behind writing our own I/O stuff (see  
     168  reasoning behind writing our own I/O stuff (see 
    171169  loci.formats.RandomAccessStream) is 1) InputStreams are fast at reading 
    172   data sequentially, but not great for random access; 2) RandomAccessFiles are 
    173   great for random access, but not so good for sequential reading; 3) we needed 
    174   RandomAccessFile-like functionality for byte arrays; 4) we wanted to be able  
    175   to read from disk and over HTTP.  The result is a hybrid class that 
    176   extends InputStream and implements DataInput to meet all of our goals. 
     170  data sequentially, but cannot do random access; 2) RandomAccessFiles are 
     171  great for random access, but less efficient for sequential reading; 3) we 
     172  needed RandomAccessFile-like functionality for byte arrays; 4) we wanted to 
     173  be able to read from disk, over HTTP, and potentially other sources.  The 
     174  result is a hybrid class that extends InputStream and implements DataInput to 
     175  meet all of our goals. 
  • trunk/loci/formats/whats-new.txt

    r2225 r2319  
    3434* Added support for MNG 
    3535* Improved support for floating-point images 
    36 * Fixed problem with 2-channel Leica LIF data  
     36* Fixed problem with 2-channel Leica LIF data 
    3737* Minor tweaks and bugfixes in many readers 
    3838* Improved file stitching logic 
  • trunk/loci/formats/writers.txt

    r1266 r2319  
    44 
    55# LOCI Bio-Formats package for reading and converting biological file formats. 
    6 # Copyright (C) 2005-@year@ Melissa Linkert, Curtis Rueden, Chris Allan 
    7 # and Eric Kjellman. 
     6# Copyright (C) 2005-@year@ Melissa Linkert, Curtis Rueden, Chris Allan, 
     7# Eric Kjellman and Brian Loranger. 
    88# 
    99# This program is free software; you can redistribute it and/or modify 
     
    2121# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
    2222 
     23# This document is a configuration file identifying all file format writers 
     24# available to Bio-Formats, and the order in which they should be used. 
     25# Please do not edit unless you know what you are doing. 
     26 
    2327loci.formats.out.TiffWriter 
    2428loci.formats.out.JPEGWriter 
Note: See TracChangeset for help on using the changeset viewer.