188 lines
5.2 KiB
Markdown
188 lines
5.2 KiB
Markdown
# BioFormatsImageInfo
|
|
|
|
[](https://www.oracle.com/java/)
|
|
[](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
|
|
```
|