rgb-to-hsv 0.1.2

An integer RGB to HSV converter using the Chernov algorithm

RGB-to-HSV

An integer RGB ↔ HSV converter implementing the algorithm from:

Chernov, Vladimir, Jarmo Alander, and Vladimir Bochko.
"Integer-Based Accurate Conversion between RGB and HSV Color Spaces."
Computers & Electrical Engineering 46 (August 2015): 328–37.
https://doi.org/10.1016/j.compeleceng.2015.08.005

All arithmetic is performed in the integer domain to avoid floating-point rounding errors.

---

Features

• Accurate integer conversion — no floating-point rounding errors.
• Batch / image support — works on single pixels, 1-D arrays of pixels, and full 2-D images (H × W × 3 arrays).
• Flexible I/O — read/write JPEG, PNG, TIFF, BMP, WebP (via Pillow), CSV / TXT (via NumPy), and HDF5 (via h5py).
• Command-line interface — rgb2hsv convert input.png output.h5
• Tkinter GUI — rgb2hsv-gui
• python -m rgb_to_hsv shorthand.

---

Installation

# From PyPI (once published)
pip install rgb-to-hsv

# From source
git clone https://github.com/alencina-faa/RGB-to-HSV.git
cd RGB-to-HSV
pip install -e ".[dev]"

Dependencies

Package	Purpose	Required?
numpy	Array math	Yes
Pillow	Image I/O	Optional (needed for image files)
h5py	HDF5 I/O	Optional (needed for .h5 files)

---

Python API

import numpy as np
from rgb_to_hsv import rgb_to_hsv, hsv_to_rgb

# Single pixel
rgb = np.array([[255, 0, 0]], dtype=np.uint8)   # pure red
hsv = rgb_to_hsv(rgb)
# hsv[0] => (H, S, V) as uint32 integers

# Round-trip
rgb_back = hsv_to_rgb(hsv)

# Full image  (H × W × 3, uint8)
from rgb_to_hsv.io_handlers import read_image, write_image
img = read_image("photo.jpg")          # uint8 RGB
hsv_img = rgb_to_hsv(img)              # uint32 HSV
rgb_img = hsv_to_rgb(hsv_img)          # uint8 RGB
write_image("out.png", rgb_img)

Chernov integer constants

Constant	Value	Description
Chernov.E	65537	Unit hue step (1/6 of full circle)
Chernov.S_MAX	65535	Maximum saturation
Chernov.H_MAX	393222	Maximum hue (= 6 × E)

---

Command-line interface

rgb2hsv [-h] [--version] {convert} ...

Subcommands:
  convert   Convert a file from RGB→HSV or HSV→RGB

Options for convert:
  input               Input file (image / CSV / HDF5)
  output              Output file
  --reverse, -r       HSV → RGB instead of RGB → HSV
  --dataset NAME      HDF5 dataset name (default: "data")

Examples

# PNG → HDF5
rgb2hsv convert photo.png photo_hsv.h5

# HDF5 → PNG  (round-trip)
rgb2hsv convert --reverse photo_hsv.h5 photo_restored.png

# CSV of RGB rows → CSV of HSV rows
rgb2hsv convert pixels_rgb.csv pixels_hsv.csv

# via python -m
python -m rgb_to_hsv convert photo.png photo_hsv.h5

HSV storage precision: PNG vs HDF5

When you convert RGB -> HSV, the internal HSV representation uses integer channels with these ranges:

• H: 0..393222
• S: 0..65535
• V: 0..255

If you save HSV to an image format such as PNG, channels are stored as 8-bit, so H and S are quantized to 0..255 for compatibility.

• PNG HSV output: compatible and visually useful, but quantized.
• HDF5 HSV output (.h5): keeps full integer precision.

For highest-fidelity round-trips, prefer:

rgb2hsv convert photo.png photo_hsv.h5
rgb2hsv convert --reverse photo_hsv.h5 photo_restored.png

---

GUI

rgb2hsv-gui

A simple Tkinter window lets you browse for input/output files, select conversion direction, and run the conversion.

If rgb2hsv-gui is not recognized in your terminal, use one of these options:

# Option A: run as module
python -m rgb_to_hsv.gui

# Option B: activate virtual environment first (Windows PowerShell)
.venv\Scripts\Activate.ps1
rgb2hsv-gui

# Option C: call the executable directly from the virtual environment
.venv\Scripts\rgb2hsv-gui.exe

This usually happens when the package scripts were installed in .venv/Scripts but the environment is not activated in the current terminal session.

---

Running tests

pip install -e ".[dev]"
pytest

---

License

This project is licensed under the GNU General Public License v3 or later (GPLv3+). See LICENSE for details.