# BioFormatsImageInfo

[![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/)

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
```

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]
```

#### Running from JAR File

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

#### Running from Fat JAR

```shell
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

```shell
# 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

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

### Sample Code

```java
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](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
```