From 7c7c61d8196d5aa42a431022fe159b8686d67432 Mon Sep 17 00:00:00 2001 From: Yoshihiro OKUMURA Date: Wed, 29 Oct 2025 12:29:46 +0900 Subject: [PATCH] update README.md to reflect new features, usage instructions, and supported formats --- README.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 149 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 841781a..ef4a376 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,96 @@ # BioFormatsImageInfo -Metadata extraction tool based on Bio-Formats +[![Maven](https://img.shields.io/badge/Java-1.8+-blue.svg)](https://www.oracle.com/java/) +[![Bio-Formats](https://img.shields.io/badge/Bio--Formats-8.3.0-green.svg)](https://www.openmicroscopy.org/bio-formats/) -## make package +BioFormatsImageInfo is a metadata extraction and thumbnail generation tool for biomedical images, based on the [Bio-Formats](https://www.openmicroscopy.org/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: ```shell +git clone [repository-url] +cd bioformats-imageinfo mvn package ``` -## run +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) ```shell -./target/dist/bin/bioformats-imageinfo "[OPTION]" "[path to image file]" +./target/dist/bin/bioformats-imageinfo [OPTION] [path to image file] ``` -### run by jar +#### Running from JAR File ```shell -java -jar ./target/dist/lib/bioformats-imageinfo-1.2.5.jar "[OPTION]" "[path to image file]" +java -jar ./target/dist/lib/bioformats-imageinfo-1.2.6.jar [OPTION] [path to image file] ``` -### run by fat jar +#### Running from Fat JAR ```shell -java -jar ./target/bioformats-imageinfo-1.2.5-jar-with-dependencies.jar "[OPTION]" "[path to image file]" +java -jar ./target/bioformats-imageinfo-1.2.6-jar-with-dependencies.jar [OPTION] [path to image file] ``` -### OPTION +### Options + +| Option | Description | +| ------ | ------------------------------------ | +| `-M` | Output metadata in JSON format | +| `-T` | Generate and output thumbnail images | + +### Usage Examples ```shell --M output metadata --T output thumbnail +# 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 +## Library Usage + +Example of using as a library in Java applications: + +### Adding Dependencies + +```xml + + jp.riken.neurodata.tools.BioFormatsImageInfo + bioformats-imageinfo + 1.2.6 + +``` + +### Sample Code ```java import java.util.LinkedHashMap; @@ -42,16 +99,89 @@ import jp.riken.neurodata.tools.BioFormatsImageInfo; import jp.riken.neurodata.tools.BioFormatsImageException; import jp.riken.neurodata.tools.BioFormatsImageThumbnail; -String path = "[path to image file]"; +// Path to image file +String path = "path/to/your/image.tif"; String format = ""; -Map metadata = new LinkedHashMap(); -Map thumbnail = new LinkedHashMap(); +Map metadata = new LinkedHashMap<>(); +Map thumbnail = new LinkedHashMap<>(); try { - format = BioFormatsImageInfo.readMetadata(path, metadata); - BioFormatsImageThumbnail.readThumbnail(path, thumbnail); + // 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 occurred - e.printStackTrace(); + // 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](https://docs.openmicroscopy.org/bio-formats/latest/supported-formats.html). + +## 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** + + ```shell + 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: + +```shell +java -Dloci.common.DebugTools.enableLogging=true -jar bioformats-imageinfo-1.2.6-jar-with-dependencies.jar -M image.tif +```