0
# Color Management
1

2
All shapes (primitives or the results of operations) can be assigned a color (RGBA). The color system supports various color formats and conversions between RGB, HSL, HSV, hexadecimal, and CSS color names. In all cases, functions return new results and never change the original shapes.
3

4
## Capabilities
5

6
### Color Assignment
7

8
Assign RGBA colors to geometry objects.
9

10
```javascript { .api }
11
/**
12
 * Assign the given color to the given objects
13
 * @param {Array} color - RGBA color values [r,g,b,a] where each value is between 0 and 1.0
14
 * @param {...Object} objects - Objects to apply the color to
15
 * @returns {Object|Array} New object(s) with color attribute added
16
 */
17
function colorize(color: [number, number, number] | [number, number, number, number], ...objects: any[]): any;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const { colorize } = require('@jscad/modeling').colors;
24
const { cube, sphere, cylinder } = require('@jscad/modeling').primitives;
25

26
// Assign RGB colors (alpha defaults to 1.0)
27
const redCube = colorize([1, 0, 0], cube({ size: 10 }));
28
const greenSphere = colorize([0, 1, 0], sphere({ radius: 5 }));
29

30
// Assign RGBA colors with transparency
31
const blueTransparent = colorize([0, 0, 1, 0.5], cylinder({ height: 10, radius: 3 }));
32

33
// Apply same color to multiple objects
34
const yellowShapes = colorize([1, 1, 0], redCube, greenSphere, blueTransparent);
35
```
36

37
### Color Format Conversions
38

39
#### Hexadecimal Colors
40

41
Convert between hexadecimal and RGB color formats.
42

43
```javascript { .api }
44
/**
45
 * Convert hexadecimal color string to RGB values
46
 * @param {String} hex - Hexadecimal color string (#RRGGBB or #RGB)
47
 * @returns {Array} RGB color values [r,g,b] where each value is between 0 and 1.0
48
 */
49
function hexToRgb(hex: string): [number, number, number];
50

51
/**
52
 * Convert RGB color values to hexadecimal string  
53
 * @param {Array} rgb - RGB color values [r,g,b] where each value is between 0 and 1.0
54
 * @returns {String} Hexadecimal color string #RRGGBB
55
 */
56
function rgbToHex(rgb: [number, number, number]): string;
57
```
58

59
**Usage Examples:**
60

61
```javascript
62
const { hexToRgb, rgbToHex, colorize } = require('@jscad/modeling').colors;
63
const { cube } = require('@jscad/modeling').primitives;
64

65
// Convert hex to RGB
66
const redRgb = hexToRgb('#FF0000'); // [1, 0, 0]
67
const blueRgb = hexToRgb('#0066CC'); // [0, 0.4, 0.8]
68
const shortHex = hexToRgb('#F0A');   // [1, 0, 0.667] (expanded from #FF00AA)
69

70
// Convert RGB to hex
71
const greenHex = rgbToHex([0, 1, 0]); // '#00FF00'
72
const customHex = rgbToHex([0.2, 0.6, 0.8]); // '#3399CC'
73

74
// Use hex colors with shapes
75
const hexColoredCube = colorize(hexToRgb('#FF6600'), cube({ size: 5 }));
76
```
77

78
#### HSL Colors
79

80
Convert between HSL (Hue, Saturation, Lightness) and RGB formats.
81

82
```javascript { .api }
83
/**
84
 * Convert HSL color values to RGB
85
 * @param {Array} hsl - HSL color values [h,s,l] where h is 0-360, s and l are 0-1
86
 * @returns {Array} RGB color values [r,g,b] where each value is between 0 and 1.0
87
 */
88
function hslToRgb(hsl: [number, number, number]): [number, number, number];
89

90
/**
91
 * Convert RGB color values to HSL
92
 * @param {Array} rgb - RGB color values [r,g,b] where each value is between 0 and 1.0  
93
 * @returns {Array} HSL color values [h,s,l] where h is 0-360, s and l are 0-1
94
 */
95
function rgbToHsl(rgb: [number, number, number]): [number, number, number];
96
```
97

98
**Usage Examples:**
99

100
```javascript
101
const { hslToRgb, rgbToHsl, colorize } = require('@jscad/modeling').colors;
102
const { sphere } = require('@jscad/modeling').primitives;
103

104
// Convert HSL to RGB
105
const redHsl = [0, 1, 0.5];        // Pure red
106
const redRgb = hslToRgb(redHsl);   // [1, 0, 0]
107

108
const blueHsl = [240, 1, 0.5];     // Pure blue  
109
const blueRgb = hslToRgb(blueHsl); // [0, 0, 1]
110

111
const grayHsl = [0, 0, 0.5];       // 50% gray
112
const grayRgb = hslToRgb(grayHsl); // [0.5, 0.5, 0.5]
113

114
// Convert RGB to HSL
115
const purpleRgb = [0.5, 0, 0.5];
116
const purpleHsl = rgbToHsl(purpleRgb); // [300, 1, 0.25]
117

118
// Create color variations using HSL
119
const baseHue = 120; // Green
120
const colorVariations = [];
121
for (let i = 0; i < 5; i++) {
122
  const lightness = 0.2 + (i * 0.15); // Varying lightness
123
  const hsl = [baseHue, 1, lightness];
124
  const rgb = hslToRgb(hsl);
125
  colorVariations.push(colorize(rgb, sphere({ radius: 2 + i })));
126
}
127
```
128

129
#### HSV Colors
130

131
Convert between HSV (Hue, Saturation, Value) and RGB formats.
132

133
```javascript { .api }
134
/**
135
 * Convert HSV color values to RGB
136
 * @param {Array} hsv - HSV color values [h,s,v] where h is 0-360, s and v are 0-1
137
 * @returns {Array} RGB color values [r,g,b] where each value is between 0 and 1.0
138
 */
139
function hsvToRgb(hsv: [number, number, number]): [number, number, number];
140

141
/**
142
 * Convert RGB color values to HSV
143
 * @param {Array} rgb - RGB color values [r,g,b] where each value is between 0 and 1.0
144
 * @returns {Array} HSV color values [h,s,v] where h is 0-360, s and v are 0-1
145
 */
146
function rgbToHsv(rgb: [number, number, number]): [number, number, number];
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
const { hsvToRgb, rgbToHsv, colorize } = require('@jscad/modeling').colors;
153
const { cylinder } = require('@jscad/modeling').primitives;
154

155
// Convert HSV to RGB
156
const brightRed = [0, 1, 1];        // Hue=0, full saturation and value
157
const brightRedRgb = hsvToRgb(brightRed); // [1, 0, 0]
158

159
const darkBlue = [240, 1, 0.5];     // Blue with 50% value
160
const darkBlueRgb = hsvToRgb(darkBlue); // [0, 0, 0.5]
161

162
// Create rainbow effect using HSV
163
const rainbowCylinders = [];
164
for (let i = 0; i < 12; i++) {
165
  const hue = i * 30;  // 0° to 330° in 30° steps
166
  const hsv = [hue, 1, 1];
167
  const rgb = hsvToRgb(hsv);
168
  const coloredCylinder = colorize(rgb, 
169
    cylinder({ height: 5, radius: 1, center: [i * 3, 0, 0] })
170
  );
171
  rainbowCylinders.push(coloredCylinder);
172
}
173
```
174

175
### CSS Color Names
176

177
Convert CSS color names to RGB values.
178

179
```javascript { .api }
180
/**
181
 * Convert CSS color name to RGB values
182
 * @param {String} colorName - CSS color name (e.g., 'red', 'blue', 'cornflowerblue')
183
 * @returns {Array} RGB color values [r,g,b] where each value is between 0 and 1.0
184
 */
185
function colorNameToRgb(colorName: string): [number, number, number];
186

187
/**
188
 * Object containing all CSS color name definitions
189
 */
190
const cssColors: { [colorName: string]: [number, number, number] };
191
```
192

193
**Usage Examples:**
194

195
```javascript
196
const { colorNameToRgb, cssColors, colorize } = require('@jscad/modeling').colors;
197
const { cube } = require('@jscad/modeling').primitives;
198

199
// Use CSS color names
200
const redCube = colorize(colorNameToRgb('red'), cube({ size: 5 }));
201
const blueCube = colorize(colorNameToRgb('cornflowerblue'), cube({ size: 4 }));
202
const greenCube = colorize(colorNameToRgb('forestgreen'), cube({ size: 3 }));
203

204
// List all available CSS colors
205
const availableColors = Object.keys(cssColors);
206
console.log(`Available colors: ${availableColors.length}`);
207

208
// Create shapes with random CSS colors
209
const randomColoredShapes = availableColors.slice(0, 10).map((colorName, index) => {
210
  const rgb = colorNameToRgb(colorName);
211
  return colorize(rgb, cube({ size: 2, center: [index * 3, 0, 0] }));
212
});
213
```
214

215
### Color Utilities
216

217
#### Internal Color Functions
218

219
```javascript { .api }
220
/**
221
 * Convert hue to color component (internal utility)
222
 * @param {Number} m1 - First intermediate value
223
 * @param {Number} m2 - Second intermediate value  
224
 * @param {Number} hue - Hue value
225
 * @returns {Number} Color component value
226
 */
227
function hueToColorComponent(m1: number, m2: number, hue: number): number;
228
```
229

230
## Advanced Color Techniques
231

232
### Gradient Effects
233

234
Create gradient effects using color interpolation:
235

236
```javascript
237
const { colorize, hslToRgb } = require('@jscad/modeling').colors;
238
const { cube, translate } = require('@jscad/modeling').primitives;
239
const { union } = require('@jscad/modeling').booleans;
240

241
// Create color gradient
242
const createGradient = (startColor, endColor, steps) => {
243
  const shapes = [];
244
  
245
  for (let i = 0; i < steps; i++) {
246
    const t = i / (steps - 1); // 0 to 1
247
    
248
    // Interpolate between colors
249
    const r = startColor[0] + t * (endColor[0] - startColor[0]);
250
    const g = startColor[1] + t * (endColor[1] - startColor[1]);
251
    const b = startColor[2] + t * (endColor[2] - startColor[2]);
252
    
253
    const interpolatedColor = [r, g, b];
254
    const coloredCube = colorize(interpolatedColor, 
255
      translate([i * 2, 0, 0], cube({ size: 1.8 }))
256
    );
257
    shapes.push(coloredCube);
258
  }
259
  
260
  return union(...shapes);
261
};
262

263
const gradient = createGradient([1, 0, 0], [0, 0, 1], 10); // Red to blue
264
```
265

266
### Color Palettes
267

268
Create themed color palettes:
269

270
```javascript
271
const { colorNameToRgb, hslToRgb, colorize } = require('@jscad/modeling').colors;
272

273
// Predefined palettes
274
const palettes = {
275
  sunset: [
276
    [1, 0.6, 0],      // Orange
277
    [1, 0.3, 0.1],    // Red-orange
278
    [0.8, 0.2, 0.4],  // Deep red
279
    [0.4, 0.1, 0.6]   // Purple
280
  ],
281
  
282
  ocean: [
283
    [0, 0.8, 1],      // Light blue
284
    [0, 0.6, 0.9],    // Medium blue
285
    [0, 0.4, 0.7],    // Dark blue
286
    [0, 0.2, 0.5]     // Deep blue
287
  ],
288
  
289
  forest: [
290
    [0.6, 1, 0.2],    // Light green
291
    [0.4, 0.8, 0.2],  // Medium green
292
    [0.2, 0.6, 0.1],  // Dark green
293
    [0.1, 0.4, 0.05]  // Deep green
294
  ]
295
};
296

297
// Apply palette to shapes
298
const applyPalette = (shapes, palette) => {
299
  return shapes.map((shape, index) => {
300
    const colorIndex = index % palette.length;
301
    return colorize(palette[colorIndex], shape);
302
  });
303
};
304
```
305

306
### Color Analysis
307

308
Analyze and manipulate colors:
309

310
```javascript
311
const { rgbToHsl, hslToRgb, rgbToHsv, hsvToRgb } = require('@jscad/modeling').colors;
312

313
// Color manipulation functions
314
const adjustBrightness = (rgb, factor) => {
315
  const hsl = rgbToHsl(rgb);
316
  hsl[2] = Math.min(1, Math.max(0, hsl[2] * factor)); // Adjust lightness
317
  return hslToRgb(hsl);
318
};
319

320
const adjustSaturation = (rgb, factor) => {
321
  const hsl = rgbToHsl(rgb);
322
  hsl[1] = Math.min(1, Math.max(0, hsl[1] * factor)); // Adjust saturation
323
  return hslToRgb(hsl);
324
};
325

326
const getComplementaryColor = (rgb) => {
327
  const hsl = rgbToHsl(rgb);
328
  hsl[0] = (hsl[0] + 180) % 360; // Opposite hue
329
  return hslToRgb(hsl);
330
};
331

332
// Usage
333
const baseColor = [0.8, 0.2, 0.2]; // Dark red
334
const brighter = adjustBrightness(baseColor, 1.5);
335
const desaturated = adjustSaturation(baseColor, 0.5);
336
const complement = getComplementaryColor(baseColor);
337
```
338

339
### Manufacturing Color Considerations
340

341
Consider color requirements for different manufacturing processes:
342

343
```javascript
344
const { colorize, rgbToHex } = require('@jscad/modeling').colors;
345

346
// 3D printing color validation
347
const validatePrintingColor = (rgb) => {
348
  // Check if color is too light for visibility
349
  const luminance = 0.299 * rgb[0] + 0.587 * rgb[1] + 0.114 * rgb[2];
350
  if (luminance > 0.9) {
351
    console.warn('Color may be too light for 3D printing visibility');
352
  }
353
  
354
  // Convert to hex for printing software
355
  const hex = rgbToHex(rgb);
356
  return { rgb, hex, luminance };
357
};
358

359
// CNC machining material colors
360
const machiningMaterials = {
361
  aluminum: [0.9, 0.9, 0.9],
362
  steel: [0.5, 0.5, 0.5],
363
  brass: [0.8, 0.7, 0.4],
364
  copper: [0.7, 0.4, 0.2]
365
};
366

367
const applyMaterialColor = (shape, material) => {
368
  if (machiningMaterials[material]) {
369
    return colorize(machiningMaterials[material], shape);
370
  }
371
  throw new Error(`Unknown material: ${material}`);
372
};
373
```