gecol_core/lib.rs
1//! A perception-aware accent color extractor and dynamic theme generator.
2//!
3//! ## Table of Contents
4//!
5//! - [How to get it](#how-to-get-it)
6//! - [With cargo](#with-cargo)
7//! - [Example](#example)
8//! - [Full pipeline](#full-pipeline)
9//! - [Template syntax](#template-syntax)
10//! - [Configuration](#configuration)
11//! - [Links](#links)
12//!
13//! ## How to get it
14//!
15//! This crate is available on [crates.io](https://crates.io/crates/gecol-core).
16//!
17//! ### With cargo
18//!
19//! ```bash
20//! cargo add gecol-core
21//! ```
22//!
23//! ## Example
24//!
25//! ### Full pipeline
26//!
27//! You can extract a color, generate a theme and build a template using only
28//! a few lines of code:
29//!
30//! ```rust,no_run
31//! use gecol_core::prelude::*;
32//! # use std::collections::HashMap;
33//! # fn get_templates() -> HashMap<String, Template> { HashMap::new() }
34//!
35//! # fn main() -> Result<(), gecol_core::Error> {
36//! let config = ExtractionConfig::default();
37//!
38//! // 1. Extract the color from the given image
39//! if let Some(color) = Extractor::extract_cached("/path/img.jpg", &config, None)? {
40//! // 2. Generate theme based on that color
41//! let theme = Theme::dark(color);
42//!
43//! // 3. Build the configuration file
44//! let template = Template::new("config.toml.template", "config.toml");
45//! template.build(&theme)?;
46//!
47//! // Or when having multiple templates (more efficient)
48//! let templates: HashMap<String, Template> = get_templates();
49//! build_templates(&templates, theme)?;
50//! }
51//! # Ok(())
52//! # }
53//! ```
54//!
55//! ### Template syntax
56//!
57//! In the templates, you have access to a rich object-oriented color API:
58//!
59//! ```text
60//! background = "{{ background }}"
61//! transparent_bg = "{{ background.hexa(0.8) }}"
62//! hover_color = "{{ background.lighten(0.1) }}"
63//! border = rgba({{ primary.rgb }}aa)
64//! ```
65//!
66//! ## Configuration
67//!
68//! The [`ExtractionConfig`](crate::extract::ExtractionConfig) struct allows
69//! fine-tuning of the extraction algorithm, such as saliency bonus, warmth
70//! bias and so on. You can read more about all the fine-tuning options in the
71//! [`ExtractionConfig`](crate::extract::ExtractionConfig) documentation.
72//!
73//! ## Links
74//!
75//! - **Author:** [Martan03](https://github.com/Martan03)
76//! - **GitHub repository:** [gecol](https://github.com/Martan03/gecol)
77//! - **Package**: [crates.io](https://crates.io/crates/gecol)
78//! - **Documentation**: [docs.rs](https://docs.rs/gecol/latest/gecol/)
79//! - **Author website:** [martan03.github.io](https://martan03.github.io)
80
81mod cache;
82mod error;
83pub mod extract;
84pub mod prelude;
85pub mod template;
86pub mod theme;
87
88pub use cache::Cache;
89pub use error::Error;