Package io.scif

Provides the interfaces and default implementations for the components of SCIFIO, and the context for instantiating these components.

See: Description

Interface Summary

Interface	Description
Checker	Interface for all SCIFIO Checker components.
DataPlane<T>	Extension of the base Plane interface.
DefaultComponent	Marker interface for default class implementations.
Format	Interface for all SCIFIO formats.
Groupable	Interface for components that can group multiple files together (e.g. for Parsing metadata or reading pixels)
HasColorTable	Interface for SCIFIO components that load ColorTables during parsing.
HasFormat	Super-interface for SCIFIO components that relate back to a Format.
HasMetaTable	Interface for components that maintain a MetaTable mapping metadata names to values.
HasSource	Interface for components that can be attached to open image sources that should be closed to avoid resource leaks
ImageMetadata	ImageMetadata stores the metadata for a single image within a dataset.
Metadata	Interface for all SCIFIO Metadata objects.
MetadataService	Interface for services that work with SCIFIO metadata.
MetaTable	Marker interface for a String : Object Map.
Parser	Interface for all SCIFIO Parsers.
Plane	Top-level interface for all Plane representations in SCIFIO.
Reader	Interface for all SCIFIO Readers.
SCIFIOPlugin	Marker interface for org.scijava.plugin.SciJavaPlugin implementations in the io.scif package.
SCIFIOService	Marker interface for all SCIFIO Services.
Translator	Interface for all SCIFIO Translators.
TypedMetadata	Sub-interface for Metadata to facilitate generic parameterization of SCIFIO components.
TypedParser<M extends TypedMetadata>	Interface for all Parser implementations that use generic parameters.
TypedReader<M extends TypedMetadata,P extends DataPlane<?>>	Interface for all Reader implementations that use generic parameters.
TypedWriter<M extends TypedMetadata>	Interface for all Writer implementations that use generic parameters.
Writer	Interface for all SCIFIO writers.

Class Summary

Class	Description
AbstractChecker	Abstract superclass of all SCIFIO Checker implementations.
AbstractFormat	Abstract superclass of all SCIFIO Format implementations.
AbstractGroupable	Abstract super-class for all Groupable components.
AbstractHasFormat	Abstract superclass for all classes that implement HasFormat.
AbstractHasSource	Abstract implementation of the HasSource interface.
AbstractImageMetadata	Abstract superclass of all ImageMetadata implementations.
AbstractMetadata	Abstract superclass of all SCIFIO Metadata implementations.
AbstractParser<M extends TypedMetadata>	Abstract superclass of all SCIFIO Parser implementations.
AbstractPlane<T,P extends DataPlane<T>>	Abstract superclass for Plane implementations in SCIFIO.
AbstractReader<M extends TypedMetadata,P extends DataPlane<?>>	Abstract superclass of all SCIFIO Reader implementations.
AbstractSCIFIOPlugin	Abstract superclass of all SCIFIOPlugin implementations.
AbstractTranslator<M extends Metadata,N extends Metadata>	Abstract superclass of all SCIFIO Translator components.
AbstractWriter<M extends TypedMetadata>	Abstract superclass of all SCIFIO Writer implementations.
AxisGuesser	AxisGuesser guesses which blocks in a file pattern correspond to which dimensional axes (Z, T or C), potentially recommending an adjustment in dimension order within the files, depending on the confidence of each guess.
BufferedImagePlane	A Plane implementation using a BufferedImage for the underlying data representation.
ByteArrayPlane	A naive Plane implementation that uses byte[] for its underlying data type.
ByteArrayReader<M extends TypedMetadata>	Abstract superclass for all Reader implementations that return a ByteArrayPlane when reading datasets.
DefaultChecker	Default Checker implementation.
DefaultImageMetadata	Default implementation of ImageMetadata.
DefaultMetadata	A dummy Metadata implementation.
DefaultMetadataService	Default service for working with SCIFIO metadata.
DefaultMetaTable	Default MetaTable implementation.
DefaultParser	Default Parser implementation.
DefaultReader	Non-functional default Reader implementation.
DefaultTranslator	Basic Translator implementation.
DefaultWriter	Non-functional default Writer implementation.
FieldPrinter	This class can be used as a flag to ensure all SCIFIO components are printed in a consistent manner via their toString methods.
FilePattern	FilePattern is a collection of methods for handling file patterns, a way of succinctly representing a collection of files meant to be part of the same data series.
FilePatternBlock	FilePatternBlock represents a single block in a FilePattern.
LocationInfo	Encompasses basic metadata about a Loation.
NumberFilter	NumberFilter is a helper filter for FilePattern.findPattern().
SCIFIO	Convenience Context wrapper.

Enum Summary

Enum	Description
MetadataLevel

Exception Summary

Exception	Description
DependencyException	Exception thrown when there is an object instantiation error or error processing dependencies.
FormatException	FormatException is the exception thrown when something goes wrong performing a file format operation.
MissingLibraryException	MissingLibraryException is the exception thrown when a particular data stream or filename requires a library that is not present on the system.
UnsupportedCompressionException	UnsupportedCompressionException is the exception thrown when the compression scheme used in a particular file or stream is unsupported.

Annotation Types Summary

Annotation Type	Description
Field	Field annotation.

Package io.scif Description

Provides the interfaces and default implementations for the components of SCIFIO, and the context for instantiating these components.

Please refer to the FAQ for answers to commonly asked questions.

Support for a given image format in SCIFIO is established by implementing the Format interface. Each Format consists of six types of components:

• Checker - determines if the Format can read/write a given image.
• Metadata - data structure for all metadata that can be found in images of the associated Format.
• Parser - builds Metadata objects, without reading pixel information from the image.
• Reader - uses corresponding Metadata to produce a standard pixel representation, e.g. encapsulated in a Plane.
• Writer - uses corresponding Metadata to save pixel data to an output source of this format's type, e.g. writing to a file on disk.
• Translator - converts between two types of Metadata. Translator converts in a single direction. To avoid an NxN translation problem, typically Translators are only defined to and from format-agnostic Metadata representations. Furthermore, only writable Formats require translators to their Metadata type.

The intended workflow in SCIFIO takes an image source through the following steps:

1. Use each discovered Format's Checker to determine if that Format is compatible with the image source.
2. If a match is found, use a Parser to extract the format-specific Metadata from the image source. Format-specific information is also used at this point to populate the associated ImageMetadata information.
3. Now that we have a Metadata object, it can be attached to a Reader and used to open image Planes.
4. If we want to save these planes to a different Format, we need to use Translators to convert our parsed Metadata to the destination Metadata. This could be done by translating to and from an intermediary - e.g. an open exchange format, like OME-XML. Or, it could be done by simply translating from the source's ImageMetadata to the destination.
5. The translated Metadata is then attached to an appropriate Writer, and Planes opened by the Reader are passed, as desired, to the Writer for saving to an output source.

The SCIFIO class wraps Context instances and provides convenient access to many services.

This package also contains an ImageMetadata interface and default implementation. ImageMetadata is use as a format-agnostic representation of common image attributes. SCIFIO follows the OME syntax of what is an "image" - in that top-level is really a dataset, which are arbitrary lists of one or more images. Images are the pixel containers, and metadata can exist at both the image and dataset level.

Changes since Bio-Formats

• Converting to Format representations from the Bio-Formats Reader. Both encapsulate the functions to read and write images of a given format, but in SCIFIO the Format consists of multiple single-purpose components to address each part of image IO atomically.

  The intent of breaking this functionality down to components is two-fold: first, to ease the process of creating new formats by external developers, by designing each component to operate without consideration for how the others work. This modularity then facilitates extensibility. For example, SCIFIO comes with a simple ImageMetadata class that encapsulates a baseline of image attributes. To replace this generation with OME-XML could be as simple as adding a new OMEXML-Translator class to the classpath.

  Note that components are all aware of their Format, and thus capable of accessing related components, via the HasFormat interface.

• Leveraging the scijava-common Context. In Bio-Formats, readers held state (e.g. the current image index). In SCIFIO, as much as possible, state is removed from all components and stored in one central location (the context). This makes SCIFIO much more friendly for using in a multi-threaded environment, allowing broader incorporation in external software.

  Note that all potentially context-sensitive components can access the context in which they were created, via the Contextual interface.

  Note also that the scijava-common Context provides a standard notion of services. Thus the io.scif.services package has been heavily reworked.

• Dataset and Image terminology. In Bio-Formats, a file was a collection of series each containing multiple images. In SCIFIO, we adopt the OME terminology that you open a dataset that contains one or more images. Each image has a number of planes.

  Bio-Formats	SCIFIO
  File	Dataset
  Series	Image
  Image	Plane

• Addition of generic parameterization. Because of the prevalence of related components in individual classes, SCIFIO makes extensive use of generics to capture these relationships.

  Most of these parameters disappear at the concrete implementation level, but are present in the interfaces and abstract layers (which is representative of the desire for SCIFIO to generically define the image IO process - with the specifications of Bio-Formats being just one possible implementation).

• Serialization. The Metadata class implements Serializable. The idea behind metadata serialization is that parsing the metadata is one of the most expensive processes of image IO. If metadata can be saved for future sessions, then repeated analysis of the associated dataset can be, potentially quite significantly, sped up.

• Dimensionality changes. Bio-Formats was hard-coded to be 5D (some permutation of XYZCT). To be fully extensible SCIFIO should be N-D. The current SCIFIO implementation uses ImgLib2 Axes to get away from the strict 5D representation.

  However, many methods in SCIFIO (especially utility methods) are still effectively 5D, as they were strictly ported from Bio-Formats code. Thus this is still an area for refinement. Especially given that the parallel axis length and type arrays are somewhat confusing, when they could be replaced by a single object.

• Planes. In Bio-Formats, readers always returned byte[], or maybe Objects which were assumed to be BufferedImages. This left very few hooks for manipulation of the resultant data. In SCIFIO we define this relationship via the Plane hierarchy, which ties together the concept of an image plane + ColorTable, and facilitates future extensibility, e.g. via new Plane types.

  Currently SCIFIO provides implementations for ByteArray and BufferedImage planes, to mirror the behavior of Bio-Formats.

Future plans

NB: items with an asterisk (*) are of unknown merit and may or may not be implemented, pending discussion.

• Translate more formats! The goal is to translate all the open source formats that were supported by Bio-Formats by the end of May.
• Add default components. Currently implementing a new Format mandates the implementation of all components. However, some formats will not use all components (e.g. proprietary formats that won't have a Writer) or do not need to go beyond the abstract implementations (for many Checkers).

  To solve this and to make it easier for new developers to pick and choose what they implement, there should be a true "Default" implementation for each component. This could potentially just be the current abstract layer. The end goal is simply that one could simply create a Format class and it would compile. At that point components could be added as needed.

• Add sub-resolution API to ImageMetadata. This feature was added after the split of SCIFIO off Bio-Formats and has not been reconciled yet. It will likely involve turning ImageMetadata into a list as well, and possibly adding a third index to many methods (imageIndex within the dataset, planeIndex within the image, sub-resolution index within the plane).

• Cancel early in Parser.parse(org.scijava.io.location.Location). There should be an active flag that can be set on a Parser instance, with regular polls set up through runtime of the parse method. If the flag ever returns false, the current parsing operation is aborted.

• Create a HasSource style interface. Metadata objects should have some sort of mapping back to their source.

  Default implementation could be a 2D array, as a list of companion files for each image in the dataset.

  Ultimately this interface will be used to generate the information required for the getUsedSource equivalent methods from Bio-Formats.

• *Use a bit mask for recovering used sources. Related to the HasSource interface, when the sources are queried there should be some standard way to do so, without using an assortment of overridden methods.

  A bit mask is a simple, logical way to do so, where the bits correspond to various optional flags. For example, the noPixels flag that currently is used in Bio-Formats.

  Note that bit masks may not be the ideal implementation of this functionality. It may be better to have some sort of object that wraps an arbitrary number of flags with a similar effect. The goal is just to create a standard that will allow for extensibility without breaking API.

• Create OriginalMetadata class. Currently both Metadata and ImageMetadata maintain HashTables for general metadata storage. This should be standardized into a new class that works more intelligently in the SCIFIO framework.

  The foundation of this OriginalMetadata class will be in annotating using the Field annotation and labeling with the index for each metadata field. This annotation allows original names to be preserved easily and in a standard way.

  By making the OriginalMetadata class implement the Metadata interface, we can add translators and set up methods to automatically translate from common metadata forms to OriginalMetadata.

• *Refine filtering logic. Filtering should only be a factor during the parsing process. In Bio-Formats there was a filterMetadata flag, but in SCIFIO this is replaced by the act of translating or not. Right now that's not very clear, but may be aided by implementing the OriginalMetadata class.

  For backwards compatibility we need to ensure that setId in Bio-Formats generates both original and OME-XML metadata.

• *Generic state cache in the context. Many Bio-Formats classes cached items such as the last plane read. This behavior may still be useful. To keep SCIFIO component instances free of state, it would make sense to allow the context to cache information in a generic way. Then different instances of a given class created under the same context would behave similarly, and potentially allow for speed improvements over a completely stateless environment.

Author:

Mark Hiner

See Also:

Format, SCIFIO