tms/avdb-py
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7089b9763815f6c7900b027eb8ca4165b4a19326
avdb-py/README.md
T
tms 7089b97638 reflect project name
2026-10-04 18:26:34 -04:00

8.5 KiB
Raw Blame History

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

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

  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:

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 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.

Reference in New Issue View Git Blame Copy Permalink