8.5 KiB
8.5 KiB
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
pip install -e .
Usage
Basic Example
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
-
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
- File Pattern:
-
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
- File Pattern:
-
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
- File Pattern:
-
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
- File Pattern:
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:
pytest tests/
Appendix: File Output Analysis
Detailed Breakdown of File Outputs
When processing the example input file TESTIMG.jpeg, the following files are produced:
-
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
-
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
-
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
-
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 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.