{"id":14668947,"url":"https://github.com/philgyford/python-halftone","last_synced_at":"2025-10-22T02:59:36.117Z","repository":{"id":3823467,"uuid":"4904096","full_name":"philgyford/python-halftone","owner":"philgyford","description":"A python module that uses PIL/Pillow to give images a halftone effect","archived":false,"fork":false,"pushed_at":"2021-12-21T15:31:35.000Z","size":7724,"stargazers_count":93,"open_issues_count":2,"forks_count":27,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-07T22:47:50.073Z","etag":null,"topics":["image-processing","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/philgyford.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-07-05T10:49:27.000Z","updated_at":"2025-08-28T09:55:46.000Z","dependencies_parsed_at":"2022-09-24T05:41:44.965Z","dependency_job_id":null,"html_url":"https://github.com/philgyford/python-halftone","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/philgyford/python-halftone","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philgyford%2Fpython-halftone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philgyford%2Fpython-halftone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philgyford%2Fpython-halftone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philgyford%2Fpython-halftone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philgyford","download_url":"https://codeload.github.com/philgyford/python-halftone/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philgyford%2Fpython-halftone/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280370892,"owners_count":26319317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-22T02:00:06.515Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["image-processing","python","python3"],"created_at":"2024-09-12T02:00:53.902Z","updated_at":"2025-10-22T02:59:36.085Z","avatar_url":"https://github.com/philgyford.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# python-halftone\n\nA Python 3 module that uses [Pillow][pillow] to give images a halftone effect (see below for examples).\n\nIt is adapted from [this StackOverflow answer][so] (which includes example images) by [fraxel][fr].\n\nRunning it over large images, or with settings that create large images, can take some time.\n\nAlso see [Clay Flannigan's halftone][clay] in case that suits your needs better.\n\nNOTE: Colors in the output files are darker in JPEG files compared to PNGs. This is something to do\nwith color profiles and RGB/CMYK conversion that I don't understand.\n[Suggestions welcome on this Issue.][bug]\n\n[pillow]: http://pillow.readthedocs.io\n[so]: http://stackoverflow.com/questions/10572274/halftone-images-in-python/10575940#10575940\n[fr]: http://stackoverflow.com/users/1175101/fraxel\n[clay]: https://github.com/ClayFlannigan/halftone\n[bug]: https://github.com/philgyford/python-halftone/issues/7\n\n\n## Basic usage\n\n```python\nimport halftone\n\nh = halftone.Halftone(\"/path/to/myimage.jpg\")\nh.make()\n```\n\nWill create a new image at `/path/to/myimage_halftoned.jpg`, using the default settings.\n\n\n## Options\n\nThere are a number of options that can be added to the `make()` call, e.g.:\n\n```python\nh.make(filename_addition=\"_new\", scale=2)\n```\n\nThe full list of options:\n\n### `angles`\n\nA list of angles, in degrees, that each channel should be rotated by. If `style=\"color\"` then 4 angles, one per channel (CMYK, in that order) are required. If `style=\"grayscale\"` only 1 angle is required; any extra are ignored. Experimenting with different angles can increase or reduce moiré patterns. [More on screen angles.](http://the-print-guide.blogspot.co.uk/2009/05/halftone-screen-angles.html)\n\nDefault: `[0, 15, 30, 45]`\n\n### `antialias`\n\nA boolean value, indicating whether the circles drawn should be antialiased. Because Pillow doesn't draw antialias shapes, this is done by drawing the image at 4x the size and then reducing it to the desired size, antialiasing as part of the process.\n\nDefault: `False`\n\n### `filename_addition`\n\nWhen saving the new image, this string will be added to the original filename. e.g. if the original filename is `\"puppy.jpg\"` and `filename_addition=\"_new\"`, the saved file will be `\"puppy_new.jpg\"`.\n\nDefault: `\"_halftoned\"`\n\n### `output_format`\n\nEither `\"default\"`, `\"jpeg\"`, or `\"png\"`. What format should the halftone file be saved as? If `\"default\"` then it's the same as the original input image's format.\n\nDefault: `\"default\"`\n\n### `output_quality`\n\nWhen saving any JPEG images, what quality to use. From `0` to `100`. Pillow says to avoid anything over `95`. Has no effect on non-JPEG images.\n\nDefault: `75`\n\n### `percentage`\n\nHow much of the gray component to remove from the CMY channels and put in the K channel.\n\nDefault: `0`\n\n### `sample`\n\nWhen creating each circle in the new image, what area of pixels should that circle represent?\n\nDefault: `10`\n\n### `save_channels`\n\nWhether to save the four CMYK channels as separate images, in addition to the combined halftoned image. Boolean. The files will have the color letter appended to the filename, like `puppy_halftoned_c.jpg` for the cyan channel. Only functions if the overall `style` argument is `\"color\"`.\n\nDefault: `False`\n\n### `save_channels_format`\n\nEither `\"default\"`, `\"jpeg\"`, or `\"png\"`. If `save_channels` is `True` then what format should the four separate images be saved as? If `\"default\"` then it's the same as the original input image's format.\n\nDefault: `\"default\"`\n\n### `save_channels_style`\n\nEither `\"color\"` or `\"grayscale\"`. If `save_channels` is `True` then whether the four separate images should be saved in color or grayscale. If the overall `style` argument is `\"grayscale\"` then the four CMYK channels will always be `\"grayscale\"`, no matter what this setting.\n\nDefault: `\"color\"`\n\n### `scale`\n\nScale of the output image. The maximum output dot diameter is `sample * scale` (which is also the number of possible dot sizes).\n\nDefault `1`\n\n### `style`\n\nEither `\"color\"` or `\"grayscale\"`. For color, four screens are output, one each for cyan, magenta, yellow and black. For grayscale, only black dots are generated, only the first number in the `angles` list is used, and the `percentage` value is ignored.\n\nDefault: `\"color\"`\n\n## Examples\n\nAn example of `make()` using all options:\n\n```python\nh.make(\n    angles=[15, 75, 0, 45],\n    antialias=True,\n    filename_addition=\"_new\",\n    output_format=\"jpeg\",\n    output_quality=95,\n    percentage=50,\n    sample=5,\n    save_channels=True,\n    save_channels_format=\"jpeg\",\n    save_channels_style=\"grayscale\",\n    scale=2,\n    style=\"color\"\n)\n```\n\nSee the `examples/` directory for the example images below.\n\n### Original image\n\n![Original image of dog](examples/original.jpg?raw=True)\n\nOther than the `filename_addition` option, the images below have been created\nusing the options specified.\n\n### Default settings\n\n```python\nh.make()\n```\n\n![Original image of dog](examples/defaults.jpg?raw=True)\n\n### Custom screen angles\n\nUsing different screen angles to reduce moiré (but resulting in a different pattern).\n\n```python\nh.make(angles=[15, 45, 0, 75])\n```\n\n![Image of dog with custom screen angles](examples/angles.jpg?raw=True)\n\n### Smaller sample\n\nReducing the sample size and increasing the scale (to increase output detail).\n\n```python\nh.make(sample=5, scale=2)\n```\n\n![Image of dog with smaller sample size](examples/sample_scale.jpg?raw=True)\n\n### Antialias\n\nWith antialiased circles.\n\n```python\nh.make(antialias=True)\n```\n\n![Antialiased image of dog](examples/antialiased.jpg?raw=True)\n\n### Grayscale\n\nBlack and white, setting the angle to 45 (the default angle would be 0, resulting in circles being in rows and columns).\n\n```python\nh.make(style=\"grayscale\", angles=[45])\n```\n\n![Grayscale image of dog](examples/grayscale.jpg?raw=True)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilgyford%2Fpython-halftone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilgyford%2Fpython-halftone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilgyford%2Fpython-halftone/lists"}