# ColorTools
A commandline tool for analyzing and sorting images by their dominant colors.
## Installation
Installation is simple using `pip`:
```
$ pip install colortools
```
## Usage
For details on how to use `ColorTools`, including many examples, see the included [`ColorTools` Tutorial](docs/colortools-tutorial.md).
```
$ colortools --help
usage: colortools [-h] [--version] [--algorithm {hue_dist,kmeans}] [--n_colors N_COLORS]
[--n_colors_heuristic {auto_n_hue,auto_n_hue_binned,auto_n_binned_with_threshold,auto_n_simple_threshold}] [--skip_analysis_crop] [--exclude_bw]
[--exclude_color] [--sort {hue,saturation,value}] [--sort_reverse] [--sort_anchor SORT_ANCHOR] [--save_sorted] [--display] [--verbose]
[--output_dir OUTPUT_DIR] [--dominant_colors] [--dominant_colors_remapped] [--spectrum] [--spectrum_all_colors] [--collage] [--summary]
input
Analyze and sort images by their dominant colors.
positional arguments:
input input directory of .jpg files (or a single .jpg file)
options:
-h, --help show this help message and exit
--version show program's version number and exit
--algorithm {hue_dist,kmeans}
algorithm to use for determining the dominant color of images (default kmeans)
--n_colors N_COLORS, --n-colors N_COLORS
number of dominant colors to compute
--n_colors_heuristic {auto_n_hue,auto_n_hue_binned,auto_n_binned_with_threshold,auto_n_simple_threshold}, --n-colors-heuristic {auto_n_hue,auto_n_hue_binned,auto_n_binned_with_threshold,auto_n_simple_threshold}
heuristic used to set `n` for the clustering algorithm
--skip_analysis_crop, --skip-analysis-crop
Analyze images in their entirety, without any edge cropping.
--exclude_bw, --exclude-bw
exclude black and white images from generated graphics
--exclude_color, --exclude-color
exclude color images from generated graphics
--sort {hue,saturation,value}
sort images
--sort_reverse, --sort-reverse
reverse the image sort order
--sort_anchor SORT_ANCHOR
anchor image with which to begin sorted sequence
--save_sorted, --save-sorted
save sorted sequence of images
--display display generated graphics in addition to saving them
--verbose print a summary of the supplied arguments
--output_dir OUTPUT_DIR, --output-dir OUTPUT_DIR
Output directory for sorted .jpg files.
--dominant_colors, --dominant-colors
save dominant color visualization for each image
--dominant_colors_remapped, --dominant-colors-remapped
include remapped image in dominant color visualization; ignored if not using kmeans algorithm
--spectrum save spectrum image for the current collection of images
--spectrum_all_colors, --spectrum-all-colors
include all detected dominant colors in the spectrum graphic
--collage save a collage of the analyzed images
--summary print a summary of the analyzed images to the console
```
### Building from Source
To build from source:
```
$ python -m build
```
Then, to install the local build file using `pip`:
```
$ pip install dist/npt_colortools-VERSION-none-any.whl
```
### Tests and Coverage
To run tests with `coverage`, generate an HTML report, and open the report:
```
$ coverage run -m pytest tests && coverage html && open htmlcov/index.html
```
### Known Issues
- First run after installation is _slow_.
Raw data
{
"_id": null,
"home_page": "https://github.com/nbeckerphoto/colortools",
"name": "nbp-colortools",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "color analysis,image analysis,photography",
"author": "Nick Becker",
"author_email": "nbeckerphoto@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/15/98/e26739ac7338afc499b3d6df7bf256cd9033df9d558c649d966a6a3c5f1c/nbp-colortools-1.0.1.tar.gz",
"platform": null,
"description": "# ColorTools\n\nA commandline tool for analyzing and sorting images by their dominant colors.\n\n## Installation\nInstallation is simple using `pip`: \n\n```\n$ pip install colortools\n```\n\n## Usage\nFor details on how to use `ColorTools`, including many examples, see the included [`ColorTools` Tutorial](docs/colortools-tutorial.md). \n\n```\n$ colortools --help\nusage: colortools [-h] [--version] [--algorithm {hue_dist,kmeans}] [--n_colors N_COLORS]\n [--n_colors_heuristic {auto_n_hue,auto_n_hue_binned,auto_n_binned_with_threshold,auto_n_simple_threshold}] [--skip_analysis_crop] [--exclude_bw]\n [--exclude_color] [--sort {hue,saturation,value}] [--sort_reverse] [--sort_anchor SORT_ANCHOR] [--save_sorted] [--display] [--verbose]\n [--output_dir OUTPUT_DIR] [--dominant_colors] [--dominant_colors_remapped] [--spectrum] [--spectrum_all_colors] [--collage] [--summary]\n input\n\nAnalyze and sort images by their dominant colors.\n\npositional arguments:\n input input directory of .jpg files (or a single .jpg file)\n\noptions:\n -h, --help show this help message and exit\n --version show program's version number and exit\n --algorithm {hue_dist,kmeans}\n algorithm to use for determining the dominant color of images (default kmeans)\n --n_colors N_COLORS, --n-colors N_COLORS\n number of dominant colors to compute\n --n_colors_heuristic {auto_n_hue,auto_n_hue_binned,auto_n_binned_with_threshold,auto_n_simple_threshold}, --n-colors-heuristic {auto_n_hue,auto_n_hue_binned,auto_n_binned_with_threshold,auto_n_simple_threshold}\n heuristic used to set `n` for the clustering algorithm\n --skip_analysis_crop, --skip-analysis-crop\n Analyze images in their entirety, without any edge cropping.\n --exclude_bw, --exclude-bw\n exclude black and white images from generated graphics\n --exclude_color, --exclude-color\n exclude color images from generated graphics\n --sort {hue,saturation,value}\n sort images\n --sort_reverse, --sort-reverse\n reverse the image sort order\n --sort_anchor SORT_ANCHOR\n anchor image with which to begin sorted sequence\n --save_sorted, --save-sorted\n save sorted sequence of images\n --display display generated graphics in addition to saving them\n --verbose print a summary of the supplied arguments\n --output_dir OUTPUT_DIR, --output-dir OUTPUT_DIR\n Output directory for sorted .jpg files.\n --dominant_colors, --dominant-colors\n save dominant color visualization for each image\n --dominant_colors_remapped, --dominant-colors-remapped\n include remapped image in dominant color visualization; ignored if not using kmeans algorithm\n --spectrum save spectrum image for the current collection of images\n --spectrum_all_colors, --spectrum-all-colors\n include all detected dominant colors in the spectrum graphic\n --collage save a collage of the analyzed images\n --summary print a summary of the analyzed images to the console\n```\n\n### Building from Source\nTo build from source: \n\n```\n$ python -m build\n```\n\nThen, to install the local build file using `pip`: \n\n```\n$ pip install dist/npt_colortools-VERSION-none-any.whl\n```\n\n### Tests and Coverage\nTo run tests with `coverage`, generate an HTML report, and open the report: \n\n```\n$ coverage run -m pytest tests && coverage html && open htmlcov/index.html \n```\n\n### Known Issues\n- First run after installation is _slow_.\n",
"bugtrack_url": null,
"license": "",
"summary": "A collection of tools for analyzing and sorting images by color.",
"version": "1.0.1",
"split_keywords": [
"color analysis",
"image analysis",
"photography"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fb5fd4ef7a9270e024f823a4fa8b75b169b7400d2401429efa28bd20694f802d",
"md5": "afdc5fb924ab9dbc2a4b65debba9a2d5",
"sha256": "fe9865ab2011af78969854ddae525b1374aa0568558f7641f876b73325acc476"
},
"downloads": -1,
"filename": "nbp_colortools-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "afdc5fb924ab9dbc2a4b65debba9a2d5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22403,
"upload_time": "2023-01-23T14:02:05",
"upload_time_iso_8601": "2023-01-23T14:02:05.842598Z",
"url": "https://files.pythonhosted.org/packages/fb/5f/d4ef7a9270e024f823a4fa8b75b169b7400d2401429efa28bd20694f802d/nbp_colortools-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1598e26739ac7338afc499b3d6df7bf256cd9033df9d558c649d966a6a3c5f1c",
"md5": "a39f434de7d1461408d06db0613a6d56",
"sha256": "79c0cfac590ea6e86b85d18002b32c186d37e29f02ab7497a3740efc7367bc0e"
},
"downloads": -1,
"filename": "nbp-colortools-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "a39f434de7d1461408d06db0613a6d56",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20215,
"upload_time": "2023-01-23T14:02:07",
"upload_time_iso_8601": "2023-01-23T14:02:07.060750Z",
"url": "https://files.pythonhosted.org/packages/15/98/e26739ac7338afc499b3d6df7bf256cd9033df9d558c649d966a6a3c5f1c/nbp-colortools-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-23 14:02:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "nbeckerphoto",
"github_project": "colortools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "nbp-colortools"
}
JSON
