Metadata-Version: 2.4
Name: overview-jpeg-tools
Version: 1.1.1
Summary: Tools and utilities to read embedded JSON data from OV Vision Systems
Author-email: Overview Corporation <support@overview.ai>
Maintainer-email: Overview Corporation <support@overview.ai>
License: Proprietary
Project-URL: Homepage, https://overview.ai
Project-URL: Repository, https://github.com/overview-ai/overview-jpeg-tools
Project-URL: Documentation, https://overview.ai/docs
Project-URL: Bug Tracker, https://github.com/overview-ai/overview-jpeg-tools/issues
Keywords: jpeg,json,exif,metadata,image-processing,overview,vision-systems
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: orjson>=3.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# Overview JPEG Tools

Tools and utilities to read embedded JSON data from OV Vision Systems.

## Installation

```bash
pip install overview-jpeg-tools
```

## Requirements

- Python 3.8+

## Quick Start

```python
from overview_jpeg_tools import JpegJsonReader, NoMetadataError

# Extract JSON data from an image
reader = JpegJsonReader("path/to/image.jpg")

try:
    data = reader.extract_json()
    print(f"Found embedded data: {data}")
except NoMetadataError:
    print("No embedded JSON found")
```

## Usage

### Extract JSON from JPEG

```python
from overview_jpeg_tools import JpegJsonReader, NoMetadataError, MetadataDecodingError

# From file path
reader = JpegJsonReader("/path/to/image.jpg")
try:
    json_data = reader.extract_json()
except NoMetadataError:
    print("Image contains no JSON metadata")
except MetadataDecodingError as e:
    print(f"Failed to decode metadata: {e}")

# From bytes
with open("image.jpg", "rb") as f:
    image_bytes = f.read()
reader = JpegJsonReader(image_bytes)
json_data = reader.extract_json()
```

### Check for Embedded JSON

```python
reader = JpegJsonReader("image.jpg")
if reader.has_embedded_json():
    data = reader.extract_json()
```

### Access Raw Image Data

```python
reader = JpegJsonReader("image.jpg")
raw_bytes = reader.to_bytes()
```

## API Reference

### `JpegJsonReader`

Main class for reading JSON data from JPEG images.

#### Constructor

```python
JpegJsonReader(source: Union[str, Path, bytes, BytesIO])
```

- `source`: File path (str/Path) or binary JPEG data (bytes/BytesIO)

**Raises:**
- `ValueError`: If not a valid JPEG image
- `FileNotFoundError`: If file path doesn't exist

#### Methods

- `extract_json() -> Dict[str, Any]`: Extract and return embedded JSON data
  - **Raises:**
    - `NoMetadataError`: If the image contains no JSON metadata
    - `MetadataDecodingError`: If metadata exists but could not be decoded
- `has_embedded_json() -> bool`: Check if the image contains embedded JSON data
- `to_bytes() -> bytes`: Get the raw image data as bytes

#### Properties

- `image_data: bytes`: The raw JPEG image data
- `source_path: Optional[Path]`: The original file path if loaded from disk

### Exceptions

- `NoMetadataError`: Raised when the image contains no JSON metadata
- `MetadataDecodingError`: Raised when metadata exists but could not be decoded properly (e.g., decompression or parsing failures)


## License

Proprietary - Copyright (c) 2024-2025 Overview Corporation. All rights reserved.

## Support

For support, contact: <support@overview.ai>

Website: <https://overview.ai>
