Generating test images

Sometimes it is nice to have a file of a specific size or pixel type for testing. Bio-Formats defines an internal format used for generating test images. Test images recognized by Bio-Formats:

• must have an extension of type .fake

• must encode the image metadata using key-value pairs separated by = either in the filename or in a companion file

• may be accompanied by an INI-style companion file. A companion file must use the same basename as the fake file and be suffixed with .ini

Filename format

To generate an image file (that contains a gradient image):

touch "my-special-test-file&pixelType=uint8&sizeX=8192&sizeY=8192.fake"

Whatever is before the first & is the image name; the remaining key-value pairs, each preceded with &, set the pixel type and image dimensions. Just replace the values with whatever you need for testing. See Key-value pairs for the full description of available key/value pairs.

Companion file

You can put metadata values in a separate UTF-8 encoded .fake.ini file with the same basename as the fake file:

touch my-special-test-file.fake
echo "pixelType=uint8" >> my-special-test-file.fake.ini
echo "sizeX=8192" >> my-special-test-file.fake.ini
echo "sizeY=8192" >> my-special-test-file.fake.ini

In fact, just the .fake.ini file alone suffices:

echo "pixelType=uint8" >> my-special-test-file.fake.ini
echo "sizeX=8192" >> my-special-test-file.fake.ini
echo "sizeY=8192" >> my-special-test-file.fake.ini

If you include a “[GlobalMetadata]” section to the ini file, then all the included values will be accessible from the global metadata map:

echo "[GlobalMetadata]" >> my-special-test-file.fake.ini
echo "my.key=some.value" >> my-special-test-file.fake.ini

The .ini file can also contain one section for each series, which allows metadata such as exposure times and positions to be set for each plane:

echo "[series_0]" >> my-special-test-file.fake.ini
echo "ExposureTime_0=10" >> my-special-test-file.fake.ini
echo "ExposureTimeUnit_0=ms" >> my-special-test-file.fake.ini
echo "PositionX_0=5" >> my-special-test-file.fake.ini
echo "PositionY_0=-5" >> my-special-test-file.fake.ini
echo "PositionZ_0=1" >> my-special-test-file.fake.ini
echo "PositionXUnit_0=mm" >> my-special-test-file.fake.ini
echo "PositionYUnit_0=mm" >> my-special-test-file.fake.ini
echo "PositionZUnit_0=mm" >> my-special-test-file.fake.ini

Several keys have support for units and can be expressed as KEY=VALUE UNIT where UNIT is the symbol of the desired unit:

touch "physicalSizesUnits&physicalSizeX=1nm&physicalSizeY=1nm&physicalSizeZ=1.5km.fake"
echo "physicalSizeX=1 nm" >> physicalSizes.fake.ini
echo "physicalSizeY=10 pm" >> physicalSizes.fake.ini
echo "physicalSizeZ=.002 mm" >> physicalSizes.fake.ini

High-content screening

To generate a simple plate file:

touch "simple-plate&plates=1&plateAcqs=1&plateRows=1&plateCols=1&fields=1.fake"
touch "default-plate&plates=1.fake"
touch "default-plate&screens=0&plates=1.fake"

These will each create a single plate without a containing screen, by default in the first two cases. In the third case setting screens to zero is used to document the lack of a screen. As above a .fake.ini file can be used.

To generate a simple screen file:

touch "default-screen&screens=1.fake"

This will create a screen containing a single simple plate.

To generate a valid plate at least one of screens, plates, plateAcqs, plateRows, plateCols and fields must be greater than zero. If this condition is met then any other plate-specific values set to zero will be ignored and the defaults used. So, for example, the file:

one-key-set&screens=0&plates=0&plateRows=0&plateCols=0&plateAcqs=0&fields=1.fake

will create a simple plate with no screen.

Regions

To generate a fake file containing regions of interest:

touch "regions&points=10.fake"
touch "regions&ellipses=20.fake"
touch "regions&rectangles=5&lines=25.fake"

Replace regions in the above examples with the desired image or plate which will contain the regions, e.g.

touch "HCSanalysis&plates=1&plateRows=16&plateCols=24&rectangles=100.fake"

For each shape type, the value will specify the number of regions of interest to create where each region of interest contains a single shape of the input type. By convention, all generated regions of interests are not associated to any given Z, C or T plane.

Sub-resolutions

New in version 6.0.0.

To generate a fake file containing sub-resolutions:

touch "pyramid1&sizeX=20000&sizeY=10000&resolutions=8.fake"
touch "pyramid2&sizeX=20000&sizeY=10000&resolutions=4&resolutionScale=4.fake"

The resolutions and resolutionScale specify the number of sub-resolutions for each plane and the downsampling factor between consecutive sub-resolutions.

Key-value pairs

There are several other keys that can be added, a complete list of these, with their default values, is shown below.

Key	Value	Default
sizeX	number of pixels wide	512
sizeY	number of pixels tall	512
sizeZ	number of Z sections	1
sizeC	number of channels	1
sizeT	number of timepoints	1
thumbSizeX	number of pixels wide, for the thumbnail	0
thumbSizeY	number of pixels tall, for the thumbnail	0
pixelType	pixel type	uint8
bitsPerPixel	number of valid bits (<= number of bits implied by pixel type)	0
rgb	number of channels that are merged together	1
dimOrder	dimension order (e.g. XYZCT)	XYZCT
orderCertain	whether or not the dimension order is certain	true
little	whether or not the pixel data should be little-endian	true
interleaved	whether or not merged channels are interleaved	false
indexed	whether or not a color lookup table is present	false
falseColor	whether or not the color lookup table is just for making the image look pretty	false
metadataComplete	whether or not the metadata is complete	true
thumbnail	whether or not CoreMetadata.thumbnail is set	false
series	number of series (Images)	1
lutLength	number of entries in the color lookup table	3
scaleFactor	the scaling factor for the pixel values on each plane	1
exposureTime	time of exposure	null
acquisitionDate	timestamp formatted as “yyyy-MM-dd_HH-mm-ss”	null
screens	number of screens	0
plates	number of plates to generate	0 [1]
plateAcqs	number of plate runs	0 [1]
plateRows	number of rows per plate	0 [1]
plateCols	number of columns per plate	0 [1]
fields	number of fields per well	0 [1]
withMicrobeam	whether or not a microbeam should be added to the experiment (HCS only)	false
annLong, annDouble, annMap, annComment, annBool, annTime, annTag, annTerm, annXml	number of annotations of the given type to generate	0
physicalSizeX	real width of the pixels, supports units defaulting to microns
physicalSizeY	real height of the pixels, supports units defaulting to microns
physicalSizeZ	real depth of the pixels, supports units defaulting to microns
ChannelName_x	the channel name for channel x
color	the default color for all channels	null
color_x	the color for channel x, overrides the default color for that channel
ellipses, labels, lines, points, polygons, polylines, rectangles	the number of ROIs containing one shape of the given type to generate
ExposureTime_x	floating point exposure time for plane x [2]
ExposureTimeUnit_x	string defining the units for the corresponding ExposureTime_x [2]	seconds
PositionX_x	floating point X position for plane x [2]
PositionXUnit_x	string defining the units for the corresponding PositionX_x [2]	microns
PositionY_x	floating point Y position for plane x [2]
PositionYUnit_x	string defining the units for the corresponding PositionY_x [2]	microns
PositionZ_x	floating point Z position for plane x [2]
PositionZUnit_x	string defining the units for the corresponding PositionZ_x [2]	microns
resolutions	number of pyramid levels or sub-resolutions for each series	1
resolutionScale	for images with sub-resolutions, scaling factor between consecutive pyramid levels	2
sleepOpenBytes	number of milliseconds to sleep for when openBytes is called	0
sleepInitFile	number of milliseconds to sleep for when initFile is called	0

[1] (1,2,3,4,5)

Default value set to 1 if any of the screens, plates, plateAcqs, plateRows, plateCols or fields values is set to a value greater than zero.

[2] (1,2,3,4,5,6,7,8)

Must be stored in the INI file under a [series_n] section, where n is the 0-based series index.

For full details of these keys, how unset and default values are handled and further examples see loci.formats.in.FakeReader.

You can often work with the .fake file directly, but in some cases support for those files is disabled and so you will need to convert the file to something else. Make sure that you have Bio-Formats built and the JARs in your CLASSPATH (individual JARs or just bioformats_package.jar):

bfconvert test&pixelType=uint8&sizeX=8192&sizeY=8192.fake test.tiff

If you do not have the command line tools installed, substitute loci.formats.tools.ImageConverter for bfconvert.