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