Changes between Initial Version and Version 1 of Export


Ignore:
Timestamp:
05/12/10 17:01:54 (10 years ago)
Author:
melissa
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Export

    v1 v1  
     1== Exporting files using Bio-Formats == 
     2 
     3This guide pertains to version 4.2 and later. 
     4 
     5== Basic conversion == 
     6 
     7The first thing we need to do is set up a reader: 
     8 
     9{{{ 
     10  // create a reader that will automatically handle any supported format 
     11  IFormatReader reader = new ImageReader(); 
     12  // tell the reader where to store the metadata from the dataset 
     13  reader.setMetadataStore(MetadataTools.createOMEXMLMetadata()); 
     14  // initialize the dataset 
     15  reader.setId("/path/to/file"); 
     16}}} 
     17 
     18Now, we set up our writer: 
     19 
     20{{{ 
     21  // create a writer that will automatically handle any supported output format 
     22  IFormatWriter writer = new ImageWriter(); 
     23  // give the writer a MetadataRetrieve object, which encapsulates all of the 
     24  // dimension information for the dataset (among many other things) 
     25  writer.setMetadataRetrieve(MetadataTools.asRetrieve(reader.getMetadataStore())); 
     26  // initialize the writer 
     27  writer.setId("/path/to/output/file"); 
     28}}} 
     29 
     30Note that the extension of the file name passed to 'writer.setId(...)' determines the file format of the exported file. 
     31 
     32Now that everything is set up, we can start writing planes: 
     33 
     34{{{ 
     35  for (int series=0; series<reader.getSeriesCount(); series++) { 
     36    reader.setSeries(series); 
     37    writer.setSeries(series); 
     38 
     39    for (int image=0; image<reader.getImageCount(); image++) { 
     40      writer.saveBytes(image, reader.openBytes(image)); 
     41    } 
     42  } 
     43}}} 
     44 
     45Finally, make sure to close both the reader and the writer.  Failure to do so can cause: 
     46  - file handle leaks 
     47  - memory leaks 
     48  - truncated output files 
     49 
     50Fortunately, closing the files is very easy: 
     51 
     52{{{ 
     53  reader.close(); 
     54  writer.close(); 
     55}}} 
     56 
     57== Converting large images == 
     58 
     59The flaw in the previous example is that it requires an image plane to be fully read into memory before it can be saved.  In many cases this is fine, but if you are working with very large images (especially > 4 GB) this is problematic.  The solution is to break each image plane into a set of reasonably-sized tiles and save each tile separately - thus substantially reducing the amount of memory required for conversion. 
     60 
     61For now, we'll assume that your tile size is 1024 x 1024, though in practice you will likely want to adjust this. 
     62Assuming you have an IFormatReader and IFormatWriter set up as in the previous example, let's start writing planes: 
     63 
     64{{{ 
     65  int tileWidth = 1024; 
     66  int tileHeight = 1024; 
     67 
     68  for (int series=0; series<reader.getSeriesCount(); series++) { 
     69    reader.setSeries(series); 
     70    writer.setSeries(series); 
     71     
     72    // determine how many tiles are in each image plane 
     73    // for simplicity, we'll assume that the image width and height are multiples of 1024 
     74    int tileRows = reader.getSizeY() / tileHeight; 
     75    int tileColumns = reader.getSizeX() / tileWidth; 
     76 
     77    for (int image=0; image<reader.getImageCount(); image++) { 
     78      for (int row=0; row<tileRows; row++) { 
     79        for (int col=0; col<tileColumns; col++) { 
     80          // open a tile - in addition to the image index, we need to specify 
     81          // the (x, y) coordinate of the upper left corner of the tile, along with the 
     82          // width and height of the tile 
     83          byte[] tile = reader.openBytes(image, col * tileWidth, row * tileHeight, tileWidth, tileHeight); 
     84          writer.saveBytes(image, tile, col * tileWidth, row * tileHeight, tileWidth, tileHeight); 
     85        } 
     86      } 
     87    } 
     88  } 
     89}}} 
     90 
     91As noted, the example assumes that the width and height of the image are multiples of the tile dimensions.  Be careful, as this is not always the case; the last column and/or row may be smaller than preceding columns/rows.  An exception will be thrown if you attempt to read or write a tile that is not completely contained by the original image plane. 
     92 
     93As before, you need to close the reader and writer. 
     94 
     95== Converting to multiple files == 
     96 
     97 
     98 
     99== Known issues (r6294) == 
     100 
     101 * exported OME-XML files cannot be opened 
     102 * exporting multiple OME-TIFF files does not work correctly 
     103 * several writers do not support writing image tiles: 
     104    - APNG 
     105    - AVI 
     106    - Java 
     107    - JPEG-2000 
     108    - JPEG 
     109    - OME-TIFF/TIFF 
     110    - OME-XML