avdb-py/README.md

# AVDB-PY - 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.