bioformats-imageinfo/README.md

BioFormatsImageInfo

BioFormatsImageInfo is a metadata extraction and thumbnail generation tool for biomedical images, based on the Bio-Formats library. It supports over 150 image formats and can be used both as a command-line tool and as a Java library.

Features

• Wide Format Support: Leverages Bio-Formats' extensive format support
• Metadata Extraction: Outputs detailed image information in JSON format
• Thumbnail Generation: Creates high-quality thumbnail images
• Command-Line Ready: Suitable for batch processing and scripting
• Library Integration: Can be embedded into Java applications

Requirements

• Java 1.8 or higher
• Maven 3.0 or higher (for building)

Installation & Build

Clone and build the project:

git clone [repository-url]
cd bioformats-imageinfo
mvn package

After the build completes, the following files will be generated:

• target/dist/ - Executable distribution
• target/bioformats-imageinfo-1.2.6.jar - Standard JAR file
• target/bioformats-imageinfo-1.2.6-jar-with-dependencies.jar - Fat JAR with dependencies

Usage

Command Line Execution

Using Executable Script (Recommended)

./target/dist/bin/bioformats-imageinfo [OPTION] [path to image file]

Running from JAR File

java -jar ./target/dist/lib/bioformats-imageinfo-1.2.6.jar [OPTION] [path to image file]

Running from Fat JAR

java -jar ./target/bioformats-imageinfo-1.2.6-jar-with-dependencies.jar [OPTION] [path to image file]

Options

Option	Description
-M	Output metadata in JSON format
-T	Generate and output thumbnail images

Usage Examples

# Extract metadata
./target/dist/bin/bioformats-imageinfo -M sample.tif

# Generate thumbnail
./target/dist/bin/bioformats-imageinfo -T sample.tif

# Output both metadata and thumbnail
./target/dist/bin/bioformats-imageinfo -M -T sample.tif

Library Usage

Example of using as a library in Java applications:

Adding Dependencies

<dependency>
    <groupId>jp.riken.neurodata.tools.BioFormatsImageInfo</groupId>
    <artifactId>bioformats-imageinfo</artifactId>
    <version>1.2.6</version>
</dependency>

Sample Code

import java.util.LinkedHashMap;
import java.util.Map;
import jp.riken.neurodata.tools.BioFormatsImageInfo;
import jp.riken.neurodata.tools.BioFormatsImageException;
import jp.riken.neurodata.tools.BioFormatsImageThumbnail;

// Path to image file
String path = "path/to/your/image.tif";
String format = "";
Map<String, Object> metadata = new LinkedHashMap<>();
Map<String, Object> thumbnail = new LinkedHashMap<>();

try {
    // Read metadata
    format = BioFormatsImageInfo.readMetadata(path, metadata);

    // Generate thumbnail
    BioFormatsImageThumbnail.readThumbnail(path, thumbnail);

    // Use results
    System.out.println("Image format: " + format);
    System.out.println("Metadata: " + metadata);
    System.out.println("Thumbnail info: " + thumbnail);

} catch (BioFormatsImageException e) {
    // Error handling
    System.err.println("Error occurred while processing image: " + e.getMessage());
    e.printStackTrace();
}

Supported Image Formats

As this tool uses the Bio-Formats library, it supports a wide variety of biomedical image formats including:

• Microscopy Images: LSM, CZI, ND2, OIB, OIF, LIF, etc.
• Common Images: TIFF, JPEG, PNG, BMP, etc.
• Medical Images: DICOM
• Others: Over 150 formats

For detailed format support information, please refer to the Bio-Formats official website.

Output Formats

Metadata Output

• Structured metadata in JSON format
• Image size, pixel information, acquisition conditions, etc.
• Detailed information for each series

Thumbnail Output

• Thumbnail images in JPEG format
• Base64 encoding support for embedding
• Adjustable quality (default: 85%)

License

Please refer to the LICENSE.txt file for the license of this project.

Development & Contribution

Developed by the Neuroinformatics Unit, RIKEN Center for Brain Science. Contributions are welcome via pull requests or issues on the repository.

• Developer: Neuroinformatics Unit, RIKEN Center for Brain Science
• Project URL: https://neurodata.riken.jp

Troubleshooting

Common Issues

1. Out of Memory Error

   java -Xmx4g -jar bioformats-imageinfo-1.2.6-jar-with-dependencies.jar -M image.tif
   

2. Processing Large Files

   • Disable Bio-Formats debug mode to improve processing speed
   • Adjust JVM heap size as needed

3. Format Support

   • For unsupported formats, check the latest Bio-Formats version for support status

Log Output Configuration

When detailed logs are needed:

java -Dloci.common.DebugTools.enableLogging=true -jar bioformats-imageinfo-1.2.6-jar-with-dependencies.jar -M image.tif