# Exporting files using Bio-Formats

This guide pertains to version 4.2 and later.

## Basic conversion

The first thing we need to do is set up a reader:

    // create a reader that will automatically handle any supported format
    IFormatReader reader = new ImageReader();
    // tell the reader where to store the metadata from the dataset
    MetadataStore metadata;

    try {
      ServiceFactory factory = new ServiceFactory();
      OMEXMLService service = factory.getInstance(OMEXMLService.class);
      metadata = service.createOMEXMLMetadata();
    }
    catch (DependencyException exc) {
      throw new FormatException("Could not create OME-XML store.", exc);
    }
    catch (ServiceException exc) {
      throw new FormatException("Could not create OME-XML store.", exc);
    }

    reader.setMetadataStore(metadata);
    // initialize the dataset
    reader.setId("/path/to/file");

Now, we set up our writer:

    // create a writer that will automatically handle any supported output format
    IFormatWriter writer = new ImageWriter();
    // give the writer a MetadataRetrieve object, which encapsulates all of the
    // dimension information for the dataset (among many other things)
    OMEXMLService service = factory.getInstance(OMEXMLService.class);
    writer.setMetadataRetrieve(service.asRetrieve(reader.getMetadataStore()));
    // initialize the writer
    writer.setId("/path/to/output/file");

Note that the extension of the file name passed to ‘writer.setId(…)’ determines the file format of the exported file.

Now that everything is set up, we can start writing planes:

    for (int series=0; series<reader.getSeriesCount(); series++) {
      reader.setSeries(series);
      writer.setSeries(series);

      for (int image=0; image<reader.getImageCount(); image++) {
        writer.saveBytes(image, reader.openBytes(image));
      }
    }

Finally, make sure to close both the reader and the writer. Failure to do so can cause:

- file handle leaks

- memory leaks

- truncated output files

Fortunately, closing the files is very easy:

    reader.close();
    writer.close();

## Converting to multiple files

The recommended method of converting to multiple files is to use a single IFormatWriter, like so:

    // you should have set up a reader as in the first example
    ImageWriter writer = new ImageWriter();
    OMEXMLService service = factory.getInstance(OMEXMLService.class);
    writer.setMetadataRetrieve(service.asRetrieve(reader.getMetadataStore()));
    // replace this with your own filename definitions
    // in this example, we're going to write half of the planes to one file
    // and half of the planes to another file
    String[] outputFiles =
      new String[] {"/path/to/file/1.tiff", "/path/to/file/2.tiff"};
    writer.setId(outputFiles[0]);

    int planesPerFile = reader.getImageCount() / outputFiles.length;
    for (int file=0; file<outputFiles.length; file++) {
      writer.changeOutputFile(outputFiles[file]);
      for (int image=0; image<planesPerFile; image++) {
        int index = file * planesPerFile + image;
        writer.saveBytes(image, reader.openBytes(index));
      }
    }

    reader.close();
    writer.close();

The advantage here is that the relationship between the files is preserved when converting to formats that support multi-file datasets internally (namely OME-TIFF). If you are only converting to graphics formats (e.g. JPEG, AVI, MOV), then you could also use a separate IFormatWriter for each file, like this:

    OMEXMLService service = factory.getInstance(OMEXMLService.class);
    // again, you should have set up a reader already
    String[] outputFiles = new String[] {"/path/to/file/1.avi", "/path/to/file/2.avi"};
    int planesPerFile = reader.getImageCount() / outputFiles.length;
    for (int file=0; file<outputFiles.length; file++) {
      ImageWriter writer = new ImageWriter();
      writer.setMetadataRetrieve(service.asRetrieve(reader.getMetadataStore()));
      writer.setId(outputFiles[file]);
      for (int image=0; image<planesPerFile; image++) {
        int index = file * planesPerFile + image;
        writer.saveBytes(image, reader.openBytes(index));
      }
      writer.close();
    }

## Known issues

List of Trac tickets