Metadata-Version: 2.4
Name: jpeg2dct-numpy
Version: 1.0.0
Summary: Library providing a Python function to read JPEG image as a numpy array
Home-page: https://github.com/chunchet-ng/jpeg2dct
Author: Uber Technologies, Inc.
Author-email: 
Maintainer: Chun Chet Ng
License: "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by the text below.
         
        "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
         
        "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) 
        the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial 
        ownership of such entity.
         
        "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
         
        "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media 
        types.
         
        "Work" shall mean the work of authorship, whether in Source or Object form, made available under this License.
         
        This License governs use of the accompanying Work, and your use of the Work constitutes acceptance of this License.
         
        You may use this Work for any non-commercial purpose, subject to the restrictions in this License. Some purposes which can be non-commercial are teaching, academic research, and personal experimentation. You may also 
        distribute this Work with books or other teaching materials, or publish the Work on websites, that are intended to teach the use of the Work.
         
        You may not use or distribute this Work, or any derivative works, outputs, or results from the Work, in any form for commercial purposes. Non-exhaustive examples of commercial purposes would be running business 
        operations, licensing, leasing, or selling the Work, or distributing the Work for use with commercial products.
         
        You may modify this Work and distribute the modified Work for non-commercial purposes, however, you may not grant rights to the Work or derivative works that are broader than or in conflict with those provided by this 
        License. For example, you may not distribute modifications of the Work under terms that would permit commercial use, or under terms that purport to require the Work or derivative works to be sublicensed to others.
        
        In return, we require that you agree:
        
        1. Not to remove any copyright or other notices from the Work.
         
        2. That if you distribute the Work in Source or Object form, you will include a verbatim copy of this License.
         
        3. That if you distribute derivative works of the Work in Source form, you do so only under a license that includes all of the provisions of this License and is not in conflict with this License, and if you distribute 
        derivative works of the Work solely in Object form you do so only under a license that complies with this License.
         
        4. That if you have modified the Work or created derivative works from the Work, and distribute such modifications or derivative works, you will cause the modified files to carry prominent notices so that recipients 
        know that they are not receiving the original Work. Such notices must state: (i) that you have changed the Work; and (ii) the date of any changes.
         
        5. If you publicly use the Work or any output or result of the Work, you will provide a notice with such use that provides any person who uses, views, accesses, interacts with, or is otherwise exposed to the Work (i) 
        with information of the nature of the Work, (ii) with a link to the Work, and (iii) a notice that the Work is available under this License.
         
        6. THAT THE WORK COMES "AS IS", WITH NO WARRANTIES. THIS MEANS NO EXPRESS, IMPLIED OR STATUTORY WARRANTY, INCLUDING WITHOUT LIMITATION, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE OR ANY WARRANTY 
        OF TITLE OR NON-INFRINGEMENT. ALSO, YOU MUST PASS THIS DISCLAIMER ON WHENEVER YOU DISTRIBUTE THE WORK OR DERIVATIVE WORKS.
         
        7. THAT NEITHER UBER TECHNOLOGIES, INC. NOR ANY OF ITS AFFILIATES, SUPPLIERS, SUCCESSORS, NOR ASSIGNS WILL BE LIABLE FOR ANY DAMAGES RELATED TO THE WORK OR THIS LICENSE, INCLUDING DIRECT, INDIRECT, SPECIAL, 
        CONSEQUENTIAL OR INCIDENTAL DAMAGES, TO THE MAXIMUM EXTENT THE LAW PERMITS, NO MATTER WHAT LEGAL THEORY IT IS BASED ON. ALSO, YOU MUST PASS THIS LIMITATION OF LIABILITY ON WHENEVER YOU DISTRIBUTE THE WORK OR 
        DERIVATIVE WORKS.
         
        8. That if you sue anyone over patents that you think may apply to the Work or anyone's use of the Work, your license to the Work ends automatically.
         
        9. That your rights under the License end automatically if you breach it in any way.
         
        10. Uber Technologies, Inc. reserves all rights not expressly granted to you in this License.
        
Project-URL: Homepage, https://github.com/chunchet-ng/jpeg2dct
Project-URL: Repository, https://github.com/chunchet-ng/jpeg2dct
Project-URL: Original Repository, https://github.com/uber-research/jpeg2dct
Keywords: jpeg,dct,image-processing,numpy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.14.0
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# jpeg2dct-numpy: Fast JPEG to DCT Coefficients

[![PyPI version](https://badge.fury.io/py/jpeg2dct-numpy.svg)](https://badge.fury.io/py/jpeg2dct-numpy)
[![Python Versions](https://img.shields.io/pypi/pyversions/jpeg2dct-numpy.svg)](https://pypi.org/project/jpeg2dct-numpy/)

> **Note**: This is a NumPy-only fork of the original [uber-research/jpeg2dct](https://github.com/uber-research/jpeg2dct) with modern Python support (3.10-3.14), **pre-built wheels with bundled libjpeg**, no TensorFlow dependency, macOS Apple Silicon compatibility, and active maintenance.

This repository contains source code useful for reproducing results presented in the paper [Faster Neural Networks Straight from JPEG](https://openreview.net/forum?id=S1ry6Y1vG) (ICLR workshop 2018):

```
@inproceedings{gueguen_2018_ICLR
  title={Faster Neural Networks Straight from JPEG},
  author={Lionel Gueguen and Alex Sergeev and Ben Kadlec and Rosanne Liu and Jason Yosinski},
  booktitle={International Conference on Learning Representations},
  year={2018}
}
```

## About

The jpeg2dct-numpy library provides native Python functions to read the Discrete Cosine Transform coefficients from images encoded in JPEG format.
The I/O operation leverages standard JPEG libraries ([libjpeg](http://libjpeg.sourceforge.net/) or [libjpeg-turbo](https://libjpeg-turbo.org/)) to perform the Huffman decoding and obtain the DCT coefficients.

**✨ New:** Pre-built wheels come with **libjpeg bundled** - no need to install system dependencies for most users!

## Usage
#### Read into numpy array
```python
from jpeg2dct.numpy import load, loads


#read from a file
jpeg_file = '/<jpeg2dct dir>/test/data/DCT_16_16.jpg'
dct_y, dct_cb, dct_cr = load(jpeg_file)
print ("Y component DCT shape {} and type {}".format(dct_y.shape, dct_y.dtype))
print ("Cb component DCT shape {} and type {}".format(dct_cb.shape, dct_cb.dtype))
print ("Cr component DCT shape {} and type {}".format(dct_cr.shape, dct_cr.dtype))

#read from in memory buffer
with open(jpeg_file, 'rb') as src:
    buffer = src.read()
dct_y, dct_cb, dct_cr = loads(buffer)

```

## Installation

### Quick Install (Recommended)

**For most users**, simply install via pip - pre-built wheels include libjpeg:

```bash
pip install jpeg2dct-numpy
```

**That's it!** The pre-built wheels for **Linux, macOS, and Windows** come with **libjpeg-turbo bundled**, so you don't need to install any system dependencies.

**Supported Platforms (Pre-built Wheels):**
- 🐧 **Linux** - x86_64, manylinux_2_17+ (most modern distributions)
- 🍎 **macOS** - macOS 15+ (Sequoia), Apple Silicon (arm64)
- 🪟 **Windows** - Windows 10/11, x64
- 🐍 **Python** - 3.10, 3.11, 3.12, 3.13, 3.14

> **Note:** Older macOS versions (14 or earlier) and Intel Macs will automatically fall back to building from source, which requires installing libjpeg-turbo manually. See "Building from Source" section below.

---

### Building from Source

If you need to build from source (development, unsupported platform, or custom builds), you'll need to install libjpeg-turbo first.

<details>
<summary><b>Click to expand: Building from Source Instructions</b></summary>

#### Requirements for Building from Source
1. Python 3.10+ (tested up to Python 3.14)
2. Numpy>=1.14.0
3. **libjpeg or libjpeg-turbo** (system library - see platform-specific instructions below)
4. C++ compiler (gcc, clang, or MSVC)

#### Platform-Specific Setup

Choose the instructions for your operating system:

<details>
<summary><b>🍎 macOS (Intel & Apple Silicon)</b></summary>

Install libjpeg-turbo via Homebrew:

```bash
# Install libjpeg-turbo
brew install jpeg-turbo

# Install jpeg2dct-numpy
pip install jpeg2dct-numpy
```

The setup.py automatically detects Homebrew installations in:
- `/opt/homebrew` (Apple Silicon M1/M2/M3)
- `/usr/local` (Intel)

</details>

<details>
<summary><b>🐧 Linux (Ubuntu/Debian)</b></summary>

Install libjpeg-turbo development package:

```bash
# Update package list
sudo apt-get update

# Install libjpeg-turbo with headers
sudo apt-get install -y libjpeg-turbo8-dev

# Alternatively, install standard libjpeg (slower)
# sudo apt-get install -y libjpeg-dev

# Install jpeg2dct-numpy
pip install jpeg2dct-numpy
```

**For other Linux distributions:**

**Fedora/RHEL/CentOS:**
```bash
sudo dnf install libjpeg-turbo-devel
# or: sudo yum install libjpeg-turbo-devel
pip install jpeg2dct-numpy
```

**Arch Linux:**
```bash
sudo pacman -S libjpeg-turbo
pip install jpeg2dct-numpy
```

</details>

<details>
<summary><b>🪟 Windows</b></summary>

**Option 1: Using vcpkg (Recommended)**

```powershell
# Install vcpkg if you haven't already
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

# Install libjpeg-turbo
.\vcpkg install libjpeg-turbo:x64-windows

# Set environment variable (in the same session or permanently)
$env:VCPKG_ROOT = "C:\path\to\vcpkg"

# Install jpeg2dct-numpy
pip install jpeg2dct-numpy
```

**Option 2: Using Conda (Easier)**

```powershell
# Install libjpeg via conda
conda install -c conda-forge libjpeg-turbo

# Install jpeg2dct-numpy
pip install jpeg2dct-numpy
```

**Note**: You'll need Microsoft Visual C++ 14.0 or greater. Get it from "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/

</details>

#### Installing from Source

After installing libjpeg-turbo (see platform-specific setup above):

```bash
# Clone the repository
git clone https://github.com/chunchet-ng/jpeg2dct.git
cd jpeg2dct

# Install in development mode
pip install -e .
```

The build process automatically:
- Detects libjpeg installation paths on your platform:
  - **macOS**: Homebrew paths (`/opt/homebrew`, `/usr/local`)
  - **Linux**: System paths (`/usr/include`, `/usr/lib`, arch-specific paths)
  - **Windows**: vcpkg paths (via `VCPKG_ROOT` environment variable)
- Detects Conda environments (all platforms)
- Configures appropriate C++ compilation flags for your platform
- Links against the libjpeg library

</details>

---

### Verifying the Installation

```bash
# Test import
python -c "from jpeg2dct.numpy import load, loads; print('jpeg2dct-numpy installed successfully!')"

# Run full test suite (if you have pytest installed)
pytest -v
```

---

## Troubleshooting

> **Note:** Most issues below only apply when **building from source**. If you're using pre-built wheels via `pip install jpeg2dct-numpy`, you won't encounter these issues.

<details>
<summary><b>❌ "cannot find -ljpeg" or "jpeglib.h: No such file or directory"</b></summary>

This error only occurs when **building from source**. Pre-built wheels don't have this issue.

If building from source, this means libjpeg is not installed or not found by the compiler.

**Linux:**
```bash
# Make sure you installed the -dev package
sudo apt-get install libjpeg-turbo8-dev

# Check if library exists
ldconfig -p | grep jpeg
```

**macOS:**
```bash
# Reinstall jpeg-turbo
brew reinstall jpeg-turbo

# Check installation
brew info jpeg-turbo
```

**Windows:**
```powershell
# Make sure VCPKG_ROOT is set
echo $env:VCPKG_ROOT

# Verify libjpeg is installed
.\vcpkg list | Select-String jpeg
```

</details>

<details>
<summary><b>❌ "Microsoft Visual C++ 14.0 or greater is required" (Windows)</b></summary>

Install Microsoft C++ Build Tools:
1. Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/
2. Run the installer
3. Select "Desktop development with C++"
4. Install and restart

</details>

<details>
<summary><b>❌ ModuleNotFoundError: No module named '_dctfromjpg_wrapper'</b></summary>

The C++ extension wasn't built properly. Try:

```bash
# Clean and rebuild
pip uninstall jpeg2dct-numpy
pip install --no-cache-dir jpeg2dct-numpy

# Or from source:
pip install -e . --force-reinstall --no-cache-dir
```

</details>

<details>
<summary><b>❌ ImportError: libjpeg.so.X: cannot open shared object file (Linux)</b></summary>

If you see this error even with pre-built wheels, your system might be missing the libjpeg runtime library. Install it:

```bash
# Ubuntu/Debian
sudo apt-get install libjpeg-turbo8

# Fedora/RHEL/CentOS
sudo dnf install libjpeg-turbo
```

Note: The pre-built wheels should work without this on most modern Linux systems (manylinux compatible).

</details>

<details>
<summary><b>✓ Manual Library Path Configuration</b></summary>

If libjpeg is installed in a custom location, set environment variables:

**Linux/macOS:**
```bash
export C_INCLUDE_PATH=/path/to/jpeg/include:$C_INCLUDE_PATH
export LIBRARY_PATH=/path/to/jpeg/lib:$LIBRARY_PATH
export LD_LIBRARY_PATH=/path/to/jpeg/lib:$LD_LIBRARY_PATH
pip install jpeg2dct-numpy
```

**Windows:**
```powershell
$env:INCLUDE = "C:\path\to\jpeg\include;$env:INCLUDE"
$env:LIB = "C:\path\to\jpeg\lib;$env:LIB"
pip install jpeg2dct-numpy
```

</details>

---

## About This Fork

This fork is maintained by [Chun Chet Ng](https://github.com/chunchet-ng) and includes the following improvements over the original [uber-research/jpeg2dct](https://github.com/uber-research/jpeg2dct):

### What's New
- ✅ **Pre-built wheels with bundled libjpeg** - No system dependencies needed!
- ✅ **Python 3.10-3.14 support** (original supported up to 3.7)
- ✅ **Multi-platform wheels** - Linux (manylinux), macOS (Intel & Apple Silicon), Windows
- ✅ **Apple Silicon (M1/M2/M3) native support** for macOS
- ✅ **Automated releases** with semantic versioning
- ✅ **CI/CD with GitHub Actions** for automated testing and publishing
- ✅ **Modern Python packaging** with pyproject.toml
- ✅ **Improved documentation** with clear installation instructions
- ✅ **No TensorFlow dependency** - Pure NumPy implementation

### Why This Fork Exists
The original uber-research/jpeg2dct repository has been inactive since 2020. This fork aims to:
1. Keep the library compatible with modern Python versions
2. Provide easy installation with pre-built wheels (no compilation needed!)
3. Fix build issues on modern systems (especially macOS)
4. Provide ongoing maintenance and support
5. Make installation as simple as `pip install jpeg2dct-numpy`

### License
See [LICENSE](LICENSE) for full details.

### Contributing
Issues and pull requests are welcome!
