From 27acf31bc12dc7dc2dd1bbd9e15744033ca2aba0 Mon Sep 17 00:00:00 2001 From: Louca Dufault <40028187+loucadufault@users.noreply.github.com> Date: Thu, 6 Jan 2022 22:08:41 -0500 Subject: [PATCH] better docs intro --- README.md | 6 ++++-- docs/build/README.md | 2 +- docs/build/interfaces/Options.md | 8 ++++---- docs/build/modules/internal_.md | 4 ++-- docs/public/README.template.md | 4 +++- src/index.ts | 2 +- 6 files changed, 15 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 71d9954..1cfd3a6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ A lightweight package to generate unique and uniformly sampled colors from UUIDs. -Since the color space is only 255^3 whereas the uuid space is much larger, it is impossible to create a complete bijection, and collisions in the generated color space are more likely to happen. +The RGB color space is represented and spanned by hexadecimal numbers in the 0x000000 to 0xffffff range. We can use a simple modulo hash function (`% (0xffffff + 0x000001)` i.e. `% 0x100000`) to return numbers in that range from the decimal representation of the UUID (a base 10 39-digit integer). We then extract the red, green, and blue components from the resulting hash (which represents a specific color in hexadecimal notation) using bit masks. + +Since the color space is only 255^3 whereas the UUID space is much larger (5.3 x 10^36 possible UUIDs), it is impossible to create a complete bijection, and collisions in the generated color space are more likely to happen. # Installation: @@ -58,4 +60,4 @@ The generated color as a CSS `` notation string #### Defined in -[index.ts:64](https://github.com/loucadufault/uuid-color/blob/79f3e41/src/index.ts#L64) +[index.ts:64](https://github.com/loucadufault/uuid-color/blob/30a3faf/src/index.ts#L64) diff --git a/docs/build/README.md b/docs/build/README.md index b5cf28e..393b410 100644 --- a/docs/build/README.md +++ b/docs/build/README.md @@ -36,4 +36,4 @@ The generated color as a CSS `` notation string #### Defined in -[index.ts:64](https://github.com/loucadufault/uuid-color/blob/79f3e41/src/index.ts#L64) +[index.ts:64](https://github.com/loucadufault/uuid-color/blob/30a3faf/src/index.ts#L64) diff --git a/docs/build/interfaces/Options.md b/docs/build/interfaces/Options.md index ddb62e2..1402b75 100644 --- a/docs/build/interfaces/Options.md +++ b/docs/build/interfaces/Options.md @@ -25,7 +25,7 @@ Colors are returned as strings in the CSS data type hexadecimal or funct #### Defined in -[index.ts:40](https://github.com/loucadufault/uuid-color/blob/79f3e41/src/index.ts#L40) +[index.ts:40](https://github.com/loucadufault/uuid-color/blob/30a3faf/src/index.ts#L40) ___ @@ -33,7 +33,7 @@ ___ • `Optional` **raw**: `boolean` -Determines whether the generated color components will be rounded. +Determines whether to skip rounding the generated color components. **`remarks`** Only applies when the specified format is `"hsl"`, as this is the only output format that involves a lossy conversion (from RGB model components). @@ -42,7 +42,7 @@ Only applies when the specified format is `"hsl"`, as this is the only output fo #### Defined in -[index.ts:30](https://github.com/loucadufault/uuid-color/blob/79f3e41/src/index.ts#L30) +[index.ts:30](https://github.com/loucadufault/uuid-color/blob/30a3faf/src/index.ts#L30) ___ @@ -58,4 +58,4 @@ See [the Receivers type](../modules/internal_.md#receivers) for more details. #### Defined in -[index.ts:49](https://github.com/loucadufault/uuid-color/blob/79f3e41/src/index.ts#L49) +[index.ts:49](https://github.com/loucadufault/uuid-color/blob/30a3faf/src/index.ts#L49) diff --git a/docs/build/modules/internal_.md b/docs/build/modules/internal_.md index 8ebcdc4..24012dc 100644 --- a/docs/build/modules/internal_.md +++ b/docs/build/modules/internal_.md @@ -25,7 +25,7 @@ #### Defined in -[index.ts:15](https://github.com/loucadufault/uuid-color/blob/79f3e41/src/index.ts#L15) +[index.ts:15](https://github.com/loucadufault/uuid-color/blob/30a3faf/src/index.ts#L15) ___ @@ -35,4 +35,4 @@ ___ #### Defined in -[index.ts:13](https://github.com/loucadufault/uuid-color/blob/79f3e41/src/index.ts#L13) +[index.ts:13](https://github.com/loucadufault/uuid-color/blob/30a3faf/src/index.ts#L13) diff --git a/docs/public/README.template.md b/docs/public/README.template.md index a58c425..a44bc4c 100644 --- a/docs/public/README.template.md +++ b/docs/public/README.template.md @@ -1,6 +1,8 @@ A lightweight package to generate unique and uniformly sampled colors from UUIDs. -Since the color space is only 255^3 whereas the uuid space is much larger, it is impossible to create a complete bijection, and collisions in the generated color space are more likely to happen. +The RGB color space is represented and spanned by hexadecimal numbers in the 0x000000 to 0xffffff range. We can use a simple modulo hash function (`% (0xffffff + 0x000001)` i.e. `% 0x100000`) to return numbers in that range from the decimal representation of the UUID (a base 10 39-digit integer). We then extract the red, green, and blue components from the resulting hash (which represents a specific color in hexadecimal notation) using bit masks. + +Since the color space is only 255^3 whereas the UUID space is much larger (5.3 x 10^36 possible UUIDs), it is impossible to create a complete bijection, and collisions in the generated color space are more likely to happen. # Installation: diff --git a/src/index.ts b/src/index.ts index 179fde9..344d5bb 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,7 +20,7 @@ type Receivers = { export interface Options { /** - * Determines whether the generated color components will be rounded. + * Determines whether to skip rounding the generated color components. * * @remarks * Only applies when the specified format is `"hsl"`, as this is the only output format that involves a lossy conversion (from RGB model components).