Metadata-Version: 2.4
Name: nbp-colortools
Version: 1.1.0
Summary: A collection of tools for analyzing and sorting images by color.
Home-page: https://github.com/nbeckerphoto/colortools
Author: Nick Becker
Author-email: nbeckerphoto@gmail.com
Keywords: color analysis,image analysis,photography
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pillow>=9.2.0
Requires-Dist: scikit-learn>=1.1.1
Requires-Dist: numpy>=1.23.1
Requires-Dist: tqdm
Dynamic: license-file

# ColorTools

A commandline tool for analyzing and sorting images by their dominant colors.

## Installation
Installation is simple using `pip` (note the `-nbp` prefix!): 

```
$ pip install nbp-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}]
                  [--color_space {rgb,lab}] [--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] [--json]
                  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)
  --color_space, --color-space {rgb,lab}
                        color space to cluster in when using the kmeans algorithm
                        (default lab); ignored if not using kmeans
  --n_colors, --n-colors N_COLORS
                        number of dominant colors to compute
  --n_colors_heuristic, --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 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
  --json                print per-image results (path, sort index, dominant colors) as a
                        single JSON object to stdout, instead of the normal human-
                        readable output; intended for scripting/integration use
```

### Building from Source
To build from source: 

```
$ python -m build
```

Then, to install the local build file using `pip`: 

```
$ pip install dist/nbp_colortools-VERSION-none-any.whl
```

To rebuild/install after updates, rebuild and then use pip's `--force-reinstall` flag. 

### Tests and Coverage
Run the full test suite with `pytest .`. 

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 can be _slow_ in some environments.
