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 |
| [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.
