# Halftone Converter
An image converter to create high quality halftone images
## Key Features
- Easily halftone your images
- High-quality rendering using Cairo graphics library
- Halftones of 3 color types – Gray, RGB, and CMYK
- Color space transformation using ICC profiles
## Install
```sh
pip3 install halftone-converter
```
### Requirements
This application can be run from Python3 on any OS.
Note that [Pycairo requires Cairo core library](https://pycairo.readthedocs.io/en/latest/getting_started.html).
- 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 image files.
```sh
halftonecv INPUT.png
```
### Synopsis
The main program can be invoked either through the `halftonecv` command or through the Python main module option `python3 -m halftonecv`.
It has command line interface as shown below.
```txt
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
describe input image files (required), can be multiple
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.
### 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 and enough.
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 by outputs
By default, an alternate filename will be used if the original filename conflicts.
#### -O, --stdout
send output to standard output
Only one image can be input when using this option.
#### -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 Gray channel
#### -t DEG DEG DEG, --Angles DEG DEG DEG, --rgb-angles DEG DEG DEG
arrange dots by `DEG` degrees in each RGB channels 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 channels 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.
#### -T, --tiff, --out-tiff
save TIFF images instead of PNG images
CMYK images will always be saved 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 ingredient 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 with 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 a part of [GPL Ghostscript](https://www.ghostscript.com/) under the [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0.html).
## License
GNU Affero General Public License v3.0
Raw data
{
"_id": null,
"home_page": null,
"name": "halftone-converter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "curegit <contact@curegit.jp>",
"keywords": "image processing, halftone, cmyk colors, cairo",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/46/3d/b8551e9b8a04ef38c073ba78ab817820f13af2ec23e1415d653f5e12e98a/halftone_converter-2.6.5.tar.gz",
"platform": null,
"description": "# Halftone Converter\n\nAn image converter to create high quality halftone images\n\n## Key Features\n\n- Easily halftone your images\n- High-quality rendering using Cairo graphics library\n- Halftones of 3 color types \u2013 Gray, RGB, and CMYK\n- Color space transformation using ICC profiles\n\n\n\n## Install\n\n```sh\npip3 install halftone-converter\n```\n\n### Requirements\n\nThis application can be run from Python3 on any OS.\nNote that [Pycairo requires Cairo core library](https://pycairo.readthedocs.io/en/latest/getting_started.html).\n\n- Python >= 3.9\n- NumPy >= 1.24\n- Pillow >= 9.3\n- Pycairo >= 1.23\n- Rich >= 13.0\n\n## Usage\n\n### Quickstart\n\nThis application takes image files as input and outputs halftones as image files.\n\n```sh\nhalftonecv INPUT.png\n```\n\n### Synopsis\n\nThe main program can be invoked either through the `halftonecv` command or through the Python main module option `python3 -m halftonecv`.\nIt has command line interface as shown below.\n\n```txt\nusage: halftonecv [-h] [-v] [-q] [-V] [-e] [-g]\n [-f] [-O | -d DIR] [-P PREFIX] [-S SUFFIX]\n [-E [START]] [-p PX] [-x SCALE] [-b [{box,gaussian}]]\n [-B PX] [-F {nearest,linear,lanczos2,lanczos3,spline36}]\n [-A DEG] [-t DEG DEG DEG] [-a DEG DEG DEG DEG]\n [-m {auto,gray,rgb,cmyk}] [-o {auto,gray,rgb,cmyk}] [-T]\n [-G GRAY_ICC_FILE] [-I RGB_ICC_FILE] [-M CMYK_ICC_FILE]\n [-L GRAY_ICC_FILE] [-l {per,sat,rel,abs,0,1,2,3}]\n [-R RGB_ICC_FILE] [-r {per,sat,rel,abs,0,1,2,3}]\n [-C CMYK_ICC_FILE] [-c {per,sat,rel,abs,0,1,2,3}] [-H] [-X]\n [--ignore] [--discard] [--opaque] [--naive] [--gamma-correction]\n [--key RATE] [-K] [--keep-red] [--keep-green] [--keep-blue]\n [--keep-cyan] [--keep-magenta] [--keep-yellow] [--keep-key]\n FILE [FILE ...]\n```\n\n### Positional Arguments\n\n#### FILE\n\ndescribe input image files (required), can be multiple\n\nPass `-` to specify standard input.\n\nInput images must be in a format that Pillow can read.\nAlso, their color mode must be Gray (L, grayscale), LA (grayscale with alpha), RGB, RGBA, P (GIF, palette based images), or CMYK.\n\n### Optional Arguments\n\n#### -h, --help\n\nshow the help message and exit\n\n#### -v, --version\n\nshow program's version number and exit\n\n#### -q, --quiet\n\nsuppress non-error messages\n\n#### -V, --traceback\n\nrender tracebacks on error\n\n#### -e, --exit\n\nstop the program immediately by an error even if jobs remain\n\nBy default, it skips failed jobs (corrupted images, etc.) and starts the next one.\n\n#### -g, --glob\n\ninterpret `FILE` values as glob patterns (e.g., `*.png`, `**/*.jpg`)\n\nUse this option if the shell's wildcard expansion is not available and enough.\nPattern `**` matches any files and zero or more directories recursively.\nThis glob function will NOT include hidden files or directories.\n\n#### -f, --force\n\noverwrite existing files by outputs\n\nBy default, an alternate filename will be used if the original filename conflicts.\n\n#### -O, --stdout\n\nsend output to standard output\n\nOnly one image can be input when using this option.\n\n#### -d DIR, --directory DIR\n\nsave output images in `DIR` directory\n\nThe directory will be created automatically if it does not exist.\n\n#### -P PREFIX, --prefix PREFIX\n\nspecify a prefix string of output filenames\n\n#### -S SUFFIX, --suffix SUFFIX\n\nspecify a suffix string of output filenames\n\n#### -E [START], --enumerate [START]\n\nuse consecutive numbers as output filenames\n\nIt counts up by one from `START`.\nThe default `START` is 1.\n\n#### -p PX, --pitch PX, --interval PX\n\narrange halftone dots at intervals of `PX` pixels in input images\n\nChange this value for desired results.\nThe default value is 4.0.\n\n#### -x SCALE, -s SCALE, --scale SCALE\n\nthe scale factor of output images to input images\n\nThe default value is 1.0.\n\n#### -b [{box,gaussian}], --blur [{box,gaussian}]\n\napply blur effect to source images\n\nIf no blur type is specified, gaussian is used.\n\n#### -B PX, --blur-radius PX\n\nspecify blur radius\n\nIf not specified, half of the pitch is used.\n\n#### -F {nearest,linear,lanczos2,lanczos3,spline36}, --resample {nearest,linear,lanczos2,lanczos3,spline36}\n\nresampling method for determining dot size\n\nThe default is `linear`.\n\n#### -A DEG, --angle DEG, --gray-angle DEG\n\narrange dots by `DEG` degrees in Gray channel\n\n#### -t DEG DEG DEG, --Angles DEG DEG DEG, --rgb-angles DEG DEG DEG\n\narrange dots by `DEG` degrees in each RGB channels respectively\n\n#### -a DEG DEG DEG DEG, --angles DEG DEG DEG DEG, --cmyk-angles DEG DEG DEG DEG\n\narrange dots by `DEG` degrees in each CMYK channels respectively\n\n#### -m {auto,gray,rgb,cmyk}, --mode {auto,gray,rgb,cmyk}\n\ncolor space type to generate halftones\n\nThe default is `auto`.\nIt means that Gray images will be Gray halftones, and colored images will be CMYK halftones.\n\n#### -o {auto,gray,rgb,cmyk}, --output {auto,gray,rgb,cmyk}\n\ncolor space type to save output images\n\nThe default is `auto`.\nIt means that Gray images will be saved as Gray images, and colored images will be saved as RGB images.\n\n#### -T, --tiff, --out-tiff\n\nsave TIFF images instead of PNG images\n\nCMYK images will always be saved in TIFF regardless of this option.\n\n#### -G GRAY_ICC_FILE, --input-gray-profile GRAY_ICC_FILE\n\nspecify ICC profile for input Gray images\n\n#### -I RGB_ICC_FILE, --input-rgb-profile RGB_ICC_FILE\n\nspecify ICC profile for input RGB images\n\n#### -M CMYK_ICC_FILE, --input-cmyk-profile CMYK_ICC_FILE\n\nspecify ICC profile for input CMYK images\n\n#### -L GRAY_ICC_FILE, --gray-profile GRAY_ICC_FILE\n\nspecify ICC profile for transform to Gray images\n\n#### -l {per,sat,rel,abs,0,1,2,3}, --gray-intent {per,sat,rel,abs,0,1,2,3}\n\nrendering intent for transform to Gray images\n\n#### -R RGB_ICC_FILE, --rgb-profile RGB_ICC_FILE\n\nspecify ICC profile for transform to RGB images\n\n#### -r {per,sat,rel,abs,0,1,2,3}, --rgb-intent {per,sat,rel,abs,0,1,2,3}\n\nrendering intent for transform to RGB images\n\n#### -C CMYK_ICC_FILE, --cmyk-profile CMYK_ICC_FILE\n\nspecify ICC profile for transform to CMYK images\n\n#### -c {per,sat,rel,abs,0,1,2,3}, --cmyk-intent {per,sat,rel,abs,0,1,2,3}\n\nrendering intent for transform to CMYK images\n\n#### -H, --allow-huge\n\ndisable the limitation of input image size\n\nBe careful in the context of server-side applications.\nThis option may make DoS attacks possible (Decompression bomb).\n\n#### -X, --orientation\n\napply Exif orientation\n\n#### --ignore, --ignore-embedded-profile\n\ndon't respect ICC profiles embedded in input images\n\n#### --discard, --discard-profile\n\ndon't embed ICC profiles in output images\n\n#### --opaque, --discard-alpha\n\ndrop alpha channel from output\n\n#### --naive, --naive-transform\n\nuse approximate color space conversion algorithm (naive transform) instead of ICC profile-based transform\n\n#### --gamma-correction\n\napply sRGB gamma correction for RGB-CMYK conversion when the naive transform is used\n\n#### --key RATE, --key-from RATE\n\nblack ingredient threshold within 0.0-1.0 for RGB-CMYK conversion when the naive transform is used\n\n#### -K, --keep-all\n\ndon't convert any channels to halftones\n\nThis is useful for previewing color space transformation.\n\n#### --keep-red\n\ndon't convert R channels to halftones\n\n#### --keep-green\n\ndon't convert G channels to halftones\n\n#### --keep-blue\n\ndon't convert B channels to halftones\n\n#### --keep-cyan\n\ndon't convert C channels to halftones\n\n#### --keep-magenta\n\ndon't convert M channels to halftones\n\n#### --keep-yellow\n\ndon't convert Y channels to halftones\n\n#### --keep-key\n\ndon't convert K channels to halftones\n\n## Gallery\n\n### RGB\n\n\n\n### CMYK\n\n\n\n### CMYK (Japan Color 2011 Coated)\n\nExample with user's custom ICC profile\n\n\n\n### Gray\n\n\n\n## Acknowledgments\n\nThis application contains some default ICC profiles to convert images between different color spaces.\n`sGray.icc`, `sRGB.icc` and `SWOP.icc` are provided by Artifex Software as a part of [GPL Ghostscript](https://www.ghostscript.com/) under the [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0.html).\n\n## License\n\nGNU Affero General Public License v3.0\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "An image converter to create high quality halftone images",
"version": "2.6.5",
"project_urls": {
"homepage": "https://github.com/curegit/halftone-converter",
"repository": "https://github.com/curegit/halftone-converter.git"
},
"split_keywords": [
"image processing",
" halftone",
" cmyk colors",
" cairo"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6c6d13c97e13309aeec91f6f4b6e9a9af4d8862aaab0814ad7c505311b8f0f13",
"md5": "1aba62f26b909b75a0107fd8e5e022d5",
"sha256": "df8f0b63a7ae92d9a5f22641dd7984e8072aaa8d15dc18dfbf402df3ee98c6ad"
},
"downloads": -1,
"filename": "halftone_converter-2.6.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1aba62f26b909b75a0107fd8e5e022d5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 173287,
"upload_time": "2024-10-26T08:17:07",
"upload_time_iso_8601": "2024-10-26T08:17:07.524334Z",
"url": "https://files.pythonhosted.org/packages/6c/6d/13c97e13309aeec91f6f4b6e9a9af4d8862aaab0814ad7c505311b8f0f13/halftone_converter-2.6.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "463db8551e9b8a04ef38c073ba78ab817820f13af2ec23e1415d653f5e12e98a",
"md5": "2ed8b2f6a10c5ed1637b9bbc354fb528",
"sha256": "706db2a264be41f70ac6e9d6484da72a73f860826c4ad30cf5e5ff22c256d82a"
},
"downloads": -1,
"filename": "halftone_converter-2.6.5.tar.gz",
"has_sig": false,
"md5_digest": "2ed8b2f6a10c5ed1637b9bbc354fb528",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 19405230,
"upload_time": "2024-10-26T08:17:11",
"upload_time_iso_8601": "2024-10-26T08:17:11.178343Z",
"url": "https://files.pythonhosted.org/packages/46/3d/b8551e9b8a04ef38c073ba78ab817820f13af2ec23e1415d653f5e12e98a/halftone_converter-2.6.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-26 08:17:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "curegit",
"github_project": "halftone-converter",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "halftone-converter"
}
JSON
