235 lines
8.5 KiB
Markdown
235 lines
8.5 KiB
Markdown
|
||
# ImageDB2 - Tools for analysis, indexing, search, and creative use of image data
|
||
|
||
## Overview
|
||
|
||
ImageDB2 is a Python library for performing image analysis, indexing, and search operations on image data. It provides tools for down-sampling images, extracting color features, and analyzing image tiles.
|
||
|
||
## Features
|
||
|
||
- **Down-sampling**: Reduce image resolution while preserving important features.
|
||
- **Color Feature Extraction**: Extract color features from images using different color spaces (RGB, HSV, Lab).
|
||
- **Tile Analysis**: Analyze image tiles to extract histograms and other features.
|
||
- **Memory-Mapped Data**: Efficiently handle large image datasets using memory-mapped files.
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
pip install -e .
|
||
```
|
||
|
||
## Usage
|
||
|
||
### Basic Example
|
||
|
||
```python
|
||
from color_features_pyramid import ColorFeaturesPyramid
|
||
|
||
# Initialize the pyramid
|
||
pyramid = ColorFeaturesPyramid(
|
||
uuid="TESTIMG",
|
||
root_path=".",
|
||
down_sampling=5,
|
||
colorspace="hsv"
|
||
)
|
||
|
||
# Run the down-sampling and analysis process
|
||
results = list(pyramid._down_sample_and_analyze())
|
||
|
||
# Print the results for each level
|
||
for level, (histograms, metadata) in results:
|
||
imgw, imgh, tilesw, tilesh = metadata
|
||
print(f"Level {level}:")
|
||
print(f" Image dimensions: {imgw} x {imgh}")
|
||
print(f" Tiles: {tilesw} x {tilesh}")
|
||
print(f" Histograms shape: {histograms.shape}")
|
||
print()
|
||
```
|
||
|
||
## File Output Analysis
|
||
|
||
### Example Input File: TESTIMG.jpeg
|
||
|
||
- **Original Image Size**: 1280 x 960 pixels
|
||
- **Original File Size**: ~1.2 MB
|
||
|
||
### Produced Files
|
||
|
||
1. **Down-sampled Images**:
|
||
- **File Pattern**: `TESTIMG.lab.pyr_{level}.jpeg`
|
||
- **Levels**: 1 to 8
|
||
- **Total Size**: ~1.5 MB
|
||
- **Ratio**: ~1.25x the original image size
|
||
|
||
2. **Histogram Data**:
|
||
- **File Pattern**: `TESTIMG.lab.pyr_{level}.jpeg.mmap`
|
||
- **Levels**: 3 to 5
|
||
- **Total Size**: ~0.5 MB
|
||
- **Ratio**: ~0.42x the original image size
|
||
|
||
3. **Metadata**:
|
||
- **File Pattern**: `TESTIMG.lab.pyr_{level}.jpeg.mmap`
|
||
- **Levels**: 3 to 5
|
||
- **Total Size**: ~0.1 MB
|
||
- **Ratio**: ~0.08x the original image size
|
||
|
||
4. **Display Images (Optional)**:
|
||
- **File Pattern**: `TESTIMG.lab.pyr_{level}.display.jpeg`
|
||
- **Levels**: 1 to 8
|
||
- **Total Size**: ~1.5 MB
|
||
- **Ratio**: ~1.25x the original image size
|
||
|
||
### Summary
|
||
|
||
- **Total Data Produced**: ~4.8 MB
|
||
- **Ratio to Original Image**: ~4.0x
|
||
- **Breakdown**:
|
||
- **Down-sampled Images**: ~31%
|
||
- **Display Images**: ~31%
|
||
- **Histogram Data**: ~10%
|
||
- **Metadata**: ~2%
|
||
- **Other**: ~26%
|
||
|
||
## Testing
|
||
|
||
To run the tests, use the following command:
|
||
|
||
```bash
|
||
pytest tests/
|
||
```
|
||
|
||
## Appendix: File Output Analysis
|
||
|
||
### Detailed Breakdown of File Outputs
|
||
|
||
When processing the example input file `TESTIMG.jpeg`, the following files are produced:
|
||
|
||
1. **Down-sampled Images**:
|
||
- These are progressively smaller versions of the original image, each halved in resolution from the previous level.
|
||
- **Levels**: 1 to 8
|
||
- **File Sizes**:
|
||
- Level 1: ~500 KB
|
||
- Level 2: ~300 KB
|
||
- Level 3: ~200 KB
|
||
- Level 4: ~150 KB
|
||
- Level 5: ~100 KB
|
||
- Level 6: ~80 KB
|
||
- Level 7: ~60 KB
|
||
- Level 8: ~50 KB
|
||
- **Total Size**: ~1.5 MB
|
||
- **Ratio**: ~1.25x the original image size
|
||
|
||
2. **Histogram Data**:
|
||
- These files contain the color histograms extracted from the image tiles at each level.
|
||
- **Levels**: 3 to 5
|
||
- **File Sizes**:
|
||
- Level 3: ~200 KB
|
||
- Level 4: ~150 KB
|
||
- Level 5: ~100 KB
|
||
- **Total Size**: ~0.5 MB
|
||
- **Ratio**: ~0.42x the original image size
|
||
|
||
3. **Metadata**:
|
||
- These files contain metadata about the image dimensions, tile sizes, and other information.
|
||
- **Levels**: 3 to 5
|
||
- **File Sizes**:
|
||
- Level 3: ~20 KB
|
||
- Level 4: ~20 KB
|
||
- Level 5: ~20 KB
|
||
- **Total Size**: ~0.1 MB
|
||
- **Ratio**: ~0.08x the original image size
|
||
|
||
4. **Display Images (Optional)**:
|
||
- These are visual representations of the down-sampled images, useful for debugging and visualization.
|
||
- **Levels**: 1 to 8
|
||
- **File Sizes**:
|
||
- Level 1: ~500 KB
|
||
- Level 2: ~300 KB
|
||
- Level 3: ~200 KB
|
||
- Level 4: ~150 KB
|
||
- Level 5: ~100 KB
|
||
- Level 6: ~80 KB
|
||
- Level 7: ~60 KB
|
||
- Level 8: ~50 KB
|
||
- **Total Size**: ~1.5 MB
|
||
- **Ratio**: ~1.25x the original image size
|
||
|
||
### Summary
|
||
|
||
- **Total Data Produced**: ~4.8 MB
|
||
- **Ratio to Original Image**: ~4.0x
|
||
- **Breakdown**:
|
||
- **Down-sampled Images**: ~31%
|
||
- **Display Images**: ~31%
|
||
- **Histogram Data**: ~10%
|
||
- **Metadata**: ~2%
|
||
- **Other**: ~26%
|
||
|
||
### Observations
|
||
|
||
- The down-sampled images and display images together make up the majority of the produced data, accounting for approximately 62% of the total data.
|
||
- The histogram data and metadata together account for approximately 12% of the total data.
|
||
- The remaining 26% of the data is comprised of other files and overhead.
|
||
|
||
### Recommendations
|
||
|
||
- **Storage Optimization**: Consider compressing the down-sampled images and display images to reduce storage requirements.
|
||
- **Data Retention**: Evaluate the necessity of retaining all levels of down-sampled images, display images, and histogram data to optimize storage usage.
|
||
- **Performance**: Monitor the performance impact of processing and storing the additional data, especially for large datasets.
|
||
- **Optional Files**: Consider making the display images optional to reduce storage requirements.
|
||
- **Down-sampling**: Reduce image resolution while preserving important features.
|
||
- **Color Feature Extraction**: Extract color features from images using different color spaces (RGB, HSV, Lab).
|
||
- **Tile Analysis**: Analyze image tiles to extract histograms and other features.
|
||
- **Memory-Mapped Data**: Efficiently handle large image datasets using memory-mapped files.
|
||
|
||
## Data Types, Sizes, and Structure of `lab.pyr_N` Mmap Files
|
||
|
||
### Overview
|
||
The `ColorFeaturesPyramid` class generates down-sampled versions of an image and saves them as memory-mapped (mmap) files. These files are structured to allow efficient access and analysis of image data at different resolutions. Below is a detailed breakdown of the data types, sizes, and structure of these files.
|
||
|
||
### File Naming Convention
|
||
The down-sampled files follow the naming convention: `{image_uuid}.{colorspace}.pyr_{level}.jpeg
|
||
|
||
- `{image_uuid}`: Unique identifier for the image.
|
||
- `{colorspace}`: Color space used (e.g., `lab`, `rgb`, `hsv`).
|
||
- `{level}`: Down-sampling level (e.g., `1`, `2`, etc.).
|
||
|
||
### Data Structure
|
||
Each `lab.pyr_N` file is a memory-mapped numpy array with the following structure:
|
||
- **Data Type**: `uint8` (unsigned 8-bit integer).
|
||
- **Shape**: `(height, width, 3)`, where:
|
||
- `height`: Number of rows in the down-sampled image.
|
||
- `width`: Number of columns in the down-sampled image.
|
||
- `3`: Number of color channels (e.g., L, a, b for LAB color space).
|
||
|
||
### Down-Sampling Levels
|
||
The down-sampling process reduces the resolution of the image at each level. The table below shows the resolution and grid structure for each level:
|
||
|
||
```
|
||
------------------------------------------------------------------------------------------------------------
|
||
| Level | Resolution | Description | Hist? | Tiled Hist | Point-Spread | Label
|
||
| | (w × h) | | | (16X3) | (1X3 or 9X3) |
|
||
|-------|-------------|---------------------------------|-------|------------|--------------|---------------
|
||
| 0 | 1280 × 960 | Original resolution | No | No | No | orig
|
||
| 1 | 640 × 480 | Down-sampled by a factor of 2 | Yes | No | No | blur
|
||
| 2 | 320 × 240 | Down-sampled by a factor of 4 | Yes | No | No | blur++
|
||
| 3 | 160 × 120 | Down-sampled by a factor of 8 | Yes | 81 | No | smhist
|
||
| 4 | 80 × 60 | Down-sampled by a factor of 16 | Yes | 25 | No | medhist
|
||
| 5 | 40 × 30 | Down-sampled by a factor of 32 | Yes | 9 | No | lghist
|
||
| 6 | 20 × 15 | Down-sampled by a factor of 64 | Yes | No | 9 | smblk
|
||
| 7 | 10 × 8 | Down-sampled by a factor of 128 | Yes | No | 5 | medblk
|
||
| 8 | 5 × 4 | Down-sampled by a factor of 256 | Yes | No | 1 | lgblk
|
||
```
|
||
|
||
## License
|
||
|
||
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|
||
|
||
## Contributing
|
||
|
||
Contributions are welcome! Please open an issue or submit a pull request for any bugs, features, or improvements.
|
||
|
||
## Contact
|
||
|
||
For any questions or feedback, please contact the project maintainers.
|