An image converter for creating high-quality halftone images
- Easily convert images to halftones
- High-quality rendering using the Cairo graphics library
- Halftones of 3 color types – Gray, RGB, and CMYK
- Color space transformation using ICC profiles
pip install halftone-converter
This application can be run with Python 3 on any OS. Note that Pycairo requires Cairo core library.
- Python >= 3.9
- NumPy >= 1.24
- Pillow >= 9.3
- Pycairo >= 1.23
- Rich >= 13.0
This application takes image files as input and outputs halftones as PNG image files.
halftonecv INPUT.jpg
The main program can be invoked either through the halftonecv command or through the Python main module option python3 -m halftonecv.
It has a command-line interface as shown below.
usage: halftonecv [-h] [-v] [-q] [-V] [-e] [-g]
[-f] [-O | -d DIR] [-P PREFIX] [-S SUFFIX]
[-E [START]] [-p PX] [-x SCALE] [-b [{box,gaussian}]]
[-B PX] [-F {nearest,linear,lanczos2,lanczos3,spline36}]
[-A DEG] [-t DEG DEG DEG] [-a DEG DEG DEG DEG]
[-m {auto,gray,rgb,cmyk}] [-o {auto,gray,rgb,cmyk}] [-T]
[-G GRAY_ICC_FILE] [-I RGB_ICC_FILE] [-M CMYK_ICC_FILE]
[-L GRAY_ICC_FILE] [-l {per,sat,rel,abs,0,1,2,3}]
[-R RGB_ICC_FILE] [-r {per,sat,rel,abs,0,1,2,3}]
[-C CMYK_ICC_FILE] [-c {per,sat,rel,abs,0,1,2,3}] [-H] [-X]
[--ignore] [--discard] [--opaque] [--naive] [--gamma-correction]
[--key RATE] [-K] [--keep-red] [--keep-green] [--keep-blue]
[--keep-cyan] [--keep-magenta] [--keep-yellow] [--keep-key]
FILE [FILE ...]Input image files (required). Multiple files are supported.
Pass - to specify standard input.
Input images must be in a format that Pillow can read. Also, their color mode must be Gray (L, grayscale), LA (grayscale with alpha), RGB, RGBA, P (GIF, palette based images), or CMYK.
-- can be used to terminate option parsing so remaining arguments are treated as positional arguments.
show the help message and exit
show program's version number and exit
suppress non-error messages
render tracebacks on error
stop the program immediately by an error even if jobs remain
By default, it skips failed jobs (corrupted images, etc.) and starts the next one.
interpret FILE values as glob patterns (e.g., *.png, **/*.jpg)
Use this option if the shell's wildcard expansion is not available or sufficient.
Pattern ** matches any files and zero or more directories recursively.
This glob function will NOT include hidden files or directories.
overwrite existing files with the output
By default, an alternate filename will be used if the original filename conflicts.
send output to standard output
Note that only one image can be input when using this option.
It can be used with a shell redirect to save with an arbitrary name, for example: halftonecv IN.jpg -O > OUT.png.
save output images in DIR directory
The directory will be created automatically if it does not exist.
specify a prefix string of output filenames
specify a suffix string of output filenames
use consecutive numbers as output filenames
It counts up by one from START.
The default START is 1.
arrange halftone dots at intervals of PX pixels in input images
Change this value for desired results. The default value is 4.0.
the scale factor of output images to input images
The default value is 1.0.
apply blur effect to source images
If no blur type is specified, gaussian is used.
specify blur radius
If not specified, half of the pitch is used.
-F {nearest,linear,lanczos2,lanczos3,spline36}, --resample {nearest,linear,lanczos2,lanczos3,spline36}
resampling method for determining dot size
The default is linear.
arrange dots by DEG degrees in the Gray channel
arrange dots by DEG degrees in each RGB channel respectively
arrange dots by DEG degrees in each CMYK channel respectively
color space type to generate halftones
The default is auto.
It means that Gray images will be Gray halftones, and colored images will be CMYK halftones.
color space type to save output images
The default is auto.
It means that Gray images will be saved as Gray images, and colored images will be saved as RGB images.
Note that CMYK images will be output in TIFF format instead of PNG.
output TIFF images instead of PNG images
CMYK images will always be output in TIFF regardless of this option.
specify ICC profile for input Gray images
specify ICC profile for input RGB images
specify ICC profile for input CMYK images
specify ICC profile for transform to Gray images
rendering intent for transform to Gray images
specify ICC profile for transform to RGB images
rendering intent for transform to RGB images
specify ICC profile for transform to CMYK images
rendering intent for transform to CMYK images
disable the limitation of input image size
Be careful in the context of server-side applications. This option may make DoS attacks possible (Decompression bomb).
apply Exif orientation
don't respect ICC profiles embedded in input images
don't embed ICC profiles in output images
drop alpha channel from output
use approximate color space conversion algorithm (naive transform) instead of ICC profile-based transform
apply sRGB gamma correction for RGB-CMYK conversion when the naive transform is used
black component threshold within 0.0-1.0 for RGB-CMYK conversion when the naive transform is used
don't convert any channels to halftones
This is useful for previewing color space transformation.
don't convert R channels to halftones
don't convert G channels to halftones
don't convert B channels to halftones
don't convert C channels to halftones
don't convert M channels to halftones
don't convert Y channels to halftones
don't convert K channels to halftones
Example using the user's custom ICC profile.
This application contains some default ICC profiles to convert images between different color spaces.
sGray.icc, sRGB.icc and SWOP.icc are provided by Artifex Software as part of GPL Ghostscript under the GNU Affero General Public License v3.0.
GNU Affero General Public License v3.0 or later
Copyright (C) 2025 curegit
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.