Skip to main content

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

Colorful Play Balls

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), PA (P with alpha), 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

RGB

Blue Hyacinths

CMYK

Todai Ramen

CMYK (Japan Color 2011 Coated)

Example using the user's custom ICC profile.

Anime Girl

Gray

Chevrolet Opala 87

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

Metadata

Release files for halftone-converter 2.6.13

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for halftone-converter 2.6.13
File Size Uploaded Provenance Actions
halftone_converter-2.6.13.tar.gz 19.4 MB Without provenance Details for halftone_converter-2.6.13.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for halftone-converter 2.6.13
File Interpreter ABI Platform Actions
halftone_converter-2.6.13-py3-none-any.whl Python 3 none any Details for halftone_converter-2.6.13-py3-none-any.whl

Total release size: 19.6 MB

Release files / halftone_converter-2.6.13.tar.gz

Download URL halftone_converter-2.6.13.tar.gz
Size 19.4 MB
Tags Source
SHA-256 checksum
How to use checksums
5cb95a979f67e665b987ccd6c51d007a7a945170372859ef88a444aaf6130781
BLAKE2b-256 checksum
How to use checksums
0e68f81ed69ce547e7ade1f0078c09bf64db82a7383e0671f7f71f5ceb0a62ef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / halftone_converter-2.6.13-py3-none-any.whl

Download URL halftone_converter-2.6.13-py3-none-any.whl
Size 174.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ac1a18480d3ee38e8f8557acf729f09753edfb5a17a936f64bb921053d49a850
BLAKE2b-256 checksum
How to use checksums
1eeea3531be73385a7e2b04c9c4d9df3288443353d9109daa68093386b6f12d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Security for halftone-converter 2.6.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.6.13 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page