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

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.