halftone-converter 2.6.10

An image converter for creating high-quality halftone images

Halftone Converter

An image converter for creating high-quality halftone images

Key Features

• 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

Installation

pip install halftone-converter

Requirements

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

Usage

Quickstart

This application takes image files as input and outputs halftones as PNG image files.

halftonecv INPUT.jpg

Synopsis

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 ...]

Positional Arguments

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.

Optional Arguments

-h, --help

show the help message and exit

-v, --version

show program's version number and exit

-q, --quiet

suppress non-error messages

-V, --traceback

render tracebacks on error

-e, --exit

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.

-g, --glob

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.

-f, --force

overwrite existing files with the output

By default, an alternate filename will be used if the original filename conflicts.

-O, --stdout

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.

-d DIR, --directory DIR

save output images in DIR directory

The directory will be created automatically if it does not exist.

-P PREFIX, --prefix PREFIX

specify a prefix string of output filenames

-S SUFFIX, --suffix SUFFIX

specify a suffix string of output filenames

-E [START], --enumerate [START]

use consecutive numbers as output filenames

It counts up by one from START. The default START is 1.

-p PX, --pitch PX, --interval PX

arrange halftone dots at intervals of PX pixels in input images

Change this value for desired results. The default value is 4.0.

-x SCALE, -s SCALE, --scale SCALE

the scale factor of output images to input images

The default value is 1.0.

-b [{box,gaussian}], --blur [{box,gaussian}]

apply blur effect to source images

If no blur type is specified, gaussian is used.

-B PX, --blur-radius PX

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.

-A DEG, --angle DEG, --gray-angle DEG

arrange dots by DEG degrees in the Gray channel

-t DEG DEG DEG, --Angles DEG DEG DEG, --rgb-angles DEG DEG DEG

arrange dots by DEG degrees in each RGB channel respectively

-a DEG DEG DEG DEG, --angles DEG DEG DEG DEG, --cmyk-angles DEG DEG DEG DEG

arrange dots by DEG degrees in each CMYK channel respectively

-m {auto,gray,rgb,cmyk}, --mode {auto,gray,rgb,cmyk}

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.

-o {auto,gray,rgb,cmyk}, --output {auto,gray,rgb,cmyk}

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.

-T, --tiff, --out-tiff

output TIFF images instead of PNG images

CMYK images will always be output in TIFF regardless of this option.

-G GRAY_ICC_FILE, --input-gray-profile GRAY_ICC_FILE

specify ICC profile for input Gray images

-I RGB_ICC_FILE, --input-rgb-profile RGB_ICC_FILE

specify ICC profile for input RGB images

-M CMYK_ICC_FILE, --input-cmyk-profile CMYK_ICC_FILE

specify ICC profile for input CMYK images

-L GRAY_ICC_FILE, --gray-profile GRAY_ICC_FILE

specify ICC profile for transform to Gray images

-l {per,sat,rel,abs,0,1,2,3}, --gray-intent {per,sat,rel,abs,0,1,2,3}

rendering intent for transform to Gray images

-R RGB_ICC_FILE, --rgb-profile RGB_ICC_FILE

specify ICC profile for transform to RGB images

-r {per,sat,rel,abs,0,1,2,3}, --rgb-intent {per,sat,rel,abs,0,1,2,3}

rendering intent for transform to RGB images

-C CMYK_ICC_FILE, --cmyk-profile CMYK_ICC_FILE

specify ICC profile for transform to CMYK images

-c {per,sat,rel,abs,0,1,2,3}, --cmyk-intent {per,sat,rel,abs,0,1,2,3}

rendering intent for transform to CMYK images

-H, --allow-huge

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).

-X, --orientation

apply Exif orientation

--ignore, --ignore-embedded-profile

don't respect ICC profiles embedded in input images

--discard, --discard-profile

don't embed ICC profiles in output images

--opaque, --discard-alpha

drop alpha channel from output

--naive, --naive-transform

use approximate color space conversion algorithm (naive transform) instead of ICC profile-based transform

--gamma-correction

apply sRGB gamma correction for RGB-CMYK conversion when the naive transform is used

--key RATE, --key-from RATE

black component threshold within 0.0-1.0 for RGB-CMYK conversion when the naive transform is used

-K, --keep-all

don't convert any channels to halftones

This is useful for previewing color space transformation.

--keep-red

don't convert R channels to halftones

--keep-green

don't convert G channels to halftones

--keep-blue

don't convert B channels to halftones

--keep-cyan

don't convert C channels to halftones

--keep-magenta

don't convert M channels to halftones

--keep-yellow

don't convert Y channels to halftones

--keep-key

don't convert K channels to halftones

Gallery

RGB

CMYK

CMYK (Japan Color 2011 Coated)

Example using the user's custom ICC profile.

Gray

Acknowledgments

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.

License

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/.