update README.md to reflect new features, usage instructions, and supported formats
This commit is contained in:
162
README.md
162
README.md
@@ -1,39 +1,96 @@
|
||||
# BioFormatsImageInfo
|
||||
|
||||
Metadata extraction tool based on Bio-Formats
|
||||
[](https://www.oracle.com/java/)
|
||||
[](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
|
||||
<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;
|
||||
@@ -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<String, Object> metadata = new LinkedHashMap<String, Object>();
|
||||
Map<String, Object> thumbnail = new LinkedHashMap<String, Object>();
|
||||
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 occurred
|
||||
// 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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user