New ImgLib container types for use with imglib-io

[curtis]

The bf-imglib adapter currently uses an ArrayContainerFactory to generate the container. We would like to have several new container types:

1) an array container type using one byte array per plane—useful for efficient Bio-Formats import, and useful for tools needing byte arrays (e.g., BufferedImage Java3D texturing by reference?)
2) an array container type using one matching primitive array per plane—useful for efficient access to pixels in ImageJ (e.g., getPixels)
3) as 1, but with an IFormatReader reference reading planes on demand—useful for efficient memory use for tools wanting matching primitive arrays (e.g., virtual stacks in ImageJ)
4) as 2, but with an IFormatReader reference reading planes on demand—useful for efficient memory use

[curtis]

Type 2 now exists as Planar*Array in  mpicbg/imglib/container/basictypecontainer/array of the imglib maven branch.

The other types are less urgent so I am pushing this ticket to a later milestone.

[curtis]

The imglib-io project (formerly bf-imglib) uses Bio-Formats to import image data using PlanarContainers (#2 above). We continue to need #3 or #4 in particular, so that Bio-Formats can deliver planes on demand from disk. This will allow us to replicate ImageJ1's "virtual stack" functionality, but more flexibly.

[curtis]

This type of work goes hand in hand with tickets #19 and #20, and makes sense as part of 2.0-beta1 development in June.

[bdezonia]

Am creating classes in imglib-io. Currently have an implementation of the VirtualRandomAccess class.

Note: IJ2's open as virtual stack plugin (or capability) will need to call ImgOpener with a correct factory or an initialized IFormatReader.

[bdezonia]

I have committed some preliminary implementations in the imglib-io package. They are untested and have some annoying features.

Ideally I'd like to create a VirtualImg from an IFormatReader. But due to generics I am forced to create a VirtualImg of a specified type (i.e. VirtualImg<ShortType>). If the underlying file type does not match an exception will get thrown at construction time.

Dues to reuse of AbstractImg we need to be provided the array of dimensions. They need to match the IFormatReader's ideas of what the dimensions are.

Finally the design requires VirtualCursors and VirtualRandomAccesses to maintain the current plane of data. And each of these cursors and accessors shares a reference to the same IFormatReader. So if multiple cursors or accessors defined we'd have memory overhead and possible threading issues. Will think about this more.

[bdezonia]

It may not be clear above but I was stating that each cursor has its own plane of data. Thus more cursors == more memory.

Also reusing AbstractImg requires dimensions to be passed to the constructor along with the IFormatReader even though the dims can be computed from the reader. We could avoid inheritance but would need to reimplement some methods. Or maybe a VirtualImg could own an AbstractImg and delegate as needed.

[bdezonia]

Final clarification: reusing the same IFormatReader for multiple cursors and accessors could be introducing a threading issues.

[curtis]

Right, we can't use the same IFormatReader for multiple threads. However, with the planned SciFIO refactoring of BF, we will be able to easily initialize multiple IFormatReaders on the same data file and use one per thread, without incurring a high initialization cost each time. So the problem will be solved eventually.

[bdezonia]

Commited code that removes the annoying construction issues related to generics, dimensions, etc. Now there is a static factory method called create(String fileName). Users get back VirtualImg<?> from this method.

Threading discussed above.

Will now write some tests.

[bdezonia]

TODO

• write and commit tests (I have small implementation uncommitted)
• the virtualSwap() code of VirtualImg has to hatch new RandomAccessors when a plane is loaded. determine if this is a PlanarContainer bug or if it can be remedied by an updateContainer() kind of call.
• refactor VirtualCursor and VirtualAccessor to share some code
• support the swapping and retrieving of planes as either primitive type arrays or always byte arrays depending upon a flag passed to the create() call.
• eventually support multiple cached planes
• eventually support writable data and write out when dirty and swapping
• I have hardcoded big vs. little endian as little I think. This works on Mac. Test if its broken on Windows. If so set little based upon running platform.
• figure out how to get TestImage loaded into project so that it is found by test runner automatically
• add TestImage to git and commit

[bdezonia]

Done

• wrote small set of tests and committed along with TestImage.tif
• test class runs and locates image correctly
• decided not to refactor VirtualCursor and VirtualAccessor - little overlap
• can swap and retrieve planes as byte[]'s only if desired

Todo

• try to eliminate the repeated creation of RandomAccessors on PlaneImg when plane swapped in (bug in PlanarContainer or some such?)
• eventually support the ability to have musltiple planes in ram and also writable data swapped out when plane is dirty
• debug big vs. little endian issues in VirtualPlaneLoader.java

[bdezonia]

Done

• eliminated need for new RandomAccessors on every plane swap
• fixed endianness initialization
• writable virtual images wil become a new ticket (or part of tiling ticket)

Curtis, please review my implementation at some point to confirm that what you thought was needed (some new container type I think) can be handled with existing implementation or not. If not then add details to this ticket else close. Thanks.

[bdezonia]

Implementation of VirtualImg and related classes is in the imglib-io project in the net.imglin.io.img.virtual package.

[curtis]

(In #20) This ticket is now a story describing the end goal of supporting large image data. Ticket #216 (and likely others to be added later) will indicate the actual approaches and tasks used to accomplish this goal.