color 0.2.4

A library for representing and manipulating colors
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

<div align="center">

# Color

A library for representing and manipulating colors

[![Linebender Zulip, #color channel](https://img.shields.io/badge/Linebender-%23color-blue?logo=Zulip)](https://xi.zulipchat.com/#narrow/channel/466849-color)
[![dependency status](https://deps.rs/repo/github/linebender/color/status.svg)](https://deps.rs/repo/github/linebender/color)
[![Apache 2.0 or MIT license.](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue.svg)](#license)
[![Build status](https://github.com/linebender/color/workflows/CI/badge.svg)](https://github.com/linebender/color/actions)
[![Crates.io](https://img.shields.io/crates/v/color.svg)](https://crates.io/crates/color)
[![Docs](https://docs.rs/color/badge.svg)](https://docs.rs/color)

</div>

<!-- We use cargo-rdme to update the README with the contents of lib.rs.
To edit the following section, update it in lib.rs, then run:
cargo rdme --workspace-project=color --heading-base-level=0
Full documentation at https://github.com/orium/cargo-rdme -->

<!-- Intra-doc links used in lib.rs should be evaluated here. 
See https://linebender.org/blog/doc-include/ for related discussion. -->
[libm]: https://crates.io/crates/libm

[`DynamicColor`]: https://docs.rs/color/latest/color/struct.DynamicColor.html
[`AlphaColor`]: https://docs.rs/color/latest/color/struct.AlphaColor.html
[`ColorSpace`]: https://docs.rs/color/latest/color/trait.ColorSpace.html
[`ColorSpaceTag`]: https://docs.rs/color/latest/color/enum.ColorSpaceTag.html
[`HueDirection`]: https://docs.rs/color/latest/color/enum.HueDirection.html
[`OpaqueColor`]: https://docs.rs/color/latest/color/struct.OpaqueColor.html
[`PremulColor`]: https://docs.rs/color/latest/color/struct.PremulColor.html
[`PremulRgba8`]: https://docs.rs/color/latest/color/struct.PremulRgba8.html
[`Rgba8`]: https://docs.rs/color/latest/color/struct.Rgba8.html
<!-- cargo-rdme start -->

Color is a Rust crate which implements color space conversions, targeting at least
[CSS Color Level 4].

## Main types

The crate has two approaches to representing color in the Rust type system: a set of
types with static color space as part of the types, and [`DynamicColor`]
in which the color space is represented at runtime.

The static color types come in three variants: [`OpaqueColor`] without an
alpha channel, [`AlphaColor`] with a separate alpha channel, and [`PremulColor`] with
premultiplied alpha. The last type is particularly useful for making interpolation and
compositing more efficient. These have a marker type parameter, indicating which
[`ColorSpace`] they are in. Conversion to another color space uses the `convert` method
on each of these types. The static types are open-ended, as it's possible to implement
this trait for new color spaces.

## Scope and goals

Color in its entirety is an extremely deep and complex topic. It is completely impractical
for a single crate to meet all color needs. The goal of this one is to strike a balance,
providing color capabilities while also keeping things simple and efficient.

The main purpose of this crate is to provide a good set of types for representing colors,
along with conversions between them and basic manipulations, especially interpolation. A
major inspiration is the [CSS Color Level 4] draft spec; we implement most of the operations
and strive for correctness.

A primary use case is rendering, including color conversions and methods for preparing
gradients. The crate should also be suitable for document authoring and editing, as it
contains methods for parsing and serializing colors with CSS Color 4 compatible syntax.

Simplifications include:
  * Always using `f32` to represent component values.
  * Only handling 3-component color spaces (plus optional alpha).
  * Choosing a fixed, curated set of color spaces for dynamic color types.
  * Choosing linear sRGB as the central color space.
  * Keeping white point implicit.

A number of other tasks are out of scope for this crate:
  * Print color spaces (CMYK).
  * Spectral colors.
  * Color spaces with more than 3 components generally.
  * [ICC] color profiles.
  * [ACES] color transforms.
  * Appearance models and other color science not needed for rendering.
  * Quantizing and packing to lower bit depths.

The [`Rgba8`] and [`PremulRgba8`] types are a partial exception to this last item, as
those representation are ubiquitous and requires special logic for serializing to
maximize compatibility.

Some of these capabilities may be added as other crates within the `color` repository,
and we will also facilitate interoperability with other color crates in the Rust
ecosystem as needed.

## Features

- `std` (enabled by default): Get floating point functions from the standard library
  (likely using your target's libc).
- `libm`: Use floating point implementations from [libm][].
- `bytemuck`: Implement traits from `bytemuck` on [`AlphaColor`], [`ColorSpaceTag`],
  [`HueDirection`], [`OpaqueColor`], [`PremulColor`], [`PremulRgba8`], and [`Rgba8`].
- `serde`: Implement `serde::Deserialize` and `serde::Serialize` on [`AlphaColor`],
  [`DynamicColor`], [`OpaqueColor`], [`PremulColor`], [`PremulRgba8`], and [`Rgba8`].

At least one of `std` and `libm` is required; `std` overrides `libm`.

[CSS Color Level 4]: https://www.w3.org/TR/css-color-4/
[ICC]: https://color.org/
[ACES]: https://acescentral.com/

<!-- cargo-rdme end -->

## Minimum supported Rust Version (MSRV)

This version of Color has been verified to compile with **Rust 1.82** and later.

Future versions of Color might increase the Rust version requirement.
It will not be treated as a breaking change and as such can even happen with small patch releases.

<details>
<summary>Click here if compiling fails.</summary>

As time has passed, some of Color's dependencies could have released versions with a higher Rust requirement.
If you encounter a compilation issue due to a dependency and don't want to upgrade your Rust toolchain, then you could downgrade the dependency.

```sh
# Use the problematic dependency's name and version
cargo update -p package_name --precise 0.1.1
```

</details>

## Community

[![Linebender Zulip](https://img.shields.io/badge/Xi%20Zulip-%23color-blue?logo=Zulip)](https://xi.zulipchat.com/#narrow/channel/466849-color)

Discussion of Color development happens in the [Linebender Zulip](https://xi.zulipchat.com/), specifically the [#color channel](https://xi.zulipchat.com/#narrow/channel/466849-color).
All public content can be read without logging in.

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.

## Contribution

Contributions are welcome by pull request. The [Rust code of conduct] applies.
Please feel free to add your name to the [AUTHORS] file in any substantive pull request.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.

[Rust Code of Conduct]: https://www.rust-lang.org/policies/code-of-conduct
[AUTHORS]: ./AUTHORS