CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-jscad--modeling

Constructive Solid Geometry (CSG) Library for 2D and 3D geometries with boolean operations, transformations, and mathematical utilities

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

colors.mddocs/

Color Management

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.

Capabilities

Color Assignment

Assign RGBA colors to geometry objects.

/**
 * Assign the given color to the given objects
 * @param {Array} color - RGBA color values [r,g,b,a] where each value is between 0 and 1.0
 * @param {...Object} objects - Objects to apply the color to
 * @returns {Object|Array} New object(s) with color attribute added
 */
function colorize(color: [number, number, number] | [number, number, number, number], ...objects: any[]): any;

Usage Examples:

const { colorize } = require('@jscad/modeling').colors;
const { cube, sphere, cylinder } = require('@jscad/modeling').primitives;

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

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

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

Color Format Conversions

Hexadecimal Colors

Convert between hexadecimal and RGB color formats.

/**
 * Convert hexadecimal color string to RGB values
 * @param {String} hex - Hexadecimal color string (#RRGGBB or #RGB)
 * @returns {Array} RGB color values [r,g,b] where each value is between 0 and 1.0
 */
function hexToRgb(hex: string): [number, number, number];

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

Usage Examples:

const { hexToRgb, rgbToHex, colorize } = require('@jscad/modeling').colors;
const { cube } = require('@jscad/modeling').primitives;

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

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

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

HSL Colors

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

/**
 * Convert HSL color values to RGB
 * @param {Array} hsl - HSL color values [h,s,l] where h is 0-360, s and l are 0-1
 * @returns {Array} RGB color values [r,g,b] where each value is between 0 and 1.0
 */
function hslToRgb(hsl: [number, number, number]): [number, number, number];

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

Usage Examples:

const { hslToRgb, rgbToHsl, colorize } = require('@jscad/modeling').colors;
const { sphere } = require('@jscad/modeling').primitives;

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

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

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

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

// Create color variations using HSL
const baseHue = 120; // Green
const colorVariations = [];
for (let i = 0; i < 5; i++) {
  const lightness = 0.2 + (i * 0.15); // Varying lightness
  const hsl = [baseHue, 1, lightness];
  const rgb = hslToRgb(hsl);
  colorVariations.push(colorize(rgb, sphere({ radius: 2 + i })));
}

HSV Colors

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

/**
 * Convert HSV color values to RGB
 * @param {Array} hsv - HSV color values [h,s,v] where h is 0-360, s and v are 0-1
 * @returns {Array} RGB color values [r,g,b] where each value is between 0 and 1.0
 */
function hsvToRgb(hsv: [number, number, number]): [number, number, number];

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

Usage Examples:

const { hsvToRgb, rgbToHsv, colorize } = require('@jscad/modeling').colors;
const { cylinder } = require('@jscad/modeling').primitives;

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

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

// Create rainbow effect using HSV
const rainbowCylinders = [];
for (let i = 0; i < 12; i++) {
  const hue = i * 30;  // 0° to 330° in 30° steps
  const hsv = [hue, 1, 1];
  const rgb = hsvToRgb(hsv);
  const coloredCylinder = colorize(rgb, 
    cylinder({ height: 5, radius: 1, center: [i * 3, 0, 0] })
  );
  rainbowCylinders.push(coloredCylinder);
}

CSS Color Names

Convert CSS color names to RGB values.

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

/**
 * Object containing all CSS color name definitions
 */
const cssColors: { [colorName: string]: [number, number, number] };

Usage Examples:

const { colorNameToRgb, cssColors, colorize } = require('@jscad/modeling').colors;
const { cube } = require('@jscad/modeling').primitives;

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

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

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

Color Utilities

Internal Color Functions

/**
 * Convert hue to color component (internal utility)
 * @param {Number} m1 - First intermediate value
 * @param {Number} m2 - Second intermediate value  
 * @param {Number} hue - Hue value
 * @returns {Number} Color component value
 */
function hueToColorComponent(m1: number, m2: number, hue: number): number;

Advanced Color Techniques

Gradient Effects

Create gradient effects using color interpolation:

const { colorize, hslToRgb } = require('@jscad/modeling').colors;
const { cube, translate } = require('@jscad/modeling').primitives;
const { union } = require('@jscad/modeling').booleans;

// Create color gradient
const createGradient = (startColor, endColor, steps) => {
  const shapes = [];
  
  for (let i = 0; i < steps; i++) {
    const t = i / (steps - 1); // 0 to 1
    
    // Interpolate between colors
    const r = startColor[0] + t * (endColor[0] - startColor[0]);
    const g = startColor[1] + t * (endColor[1] - startColor[1]);
    const b = startColor[2] + t * (endColor[2] - startColor[2]);
    
    const interpolatedColor = [r, g, b];
    const coloredCube = colorize(interpolatedColor, 
      translate([i * 2, 0, 0], cube({ size: 1.8 }))
    );
    shapes.push(coloredCube);
  }
  
  return union(...shapes);
};

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

Color Palettes

Create themed color palettes:

const { colorNameToRgb, hslToRgb, colorize } = require('@jscad/modeling').colors;

// Predefined palettes
const palettes = {
  sunset: [
    [1, 0.6, 0],      // Orange
    [1, 0.3, 0.1],    // Red-orange
    [0.8, 0.2, 0.4],  // Deep red
    [0.4, 0.1, 0.6]   // Purple
  ],
  
  ocean: [
    [0, 0.8, 1],      // Light blue
    [0, 0.6, 0.9],    // Medium blue
    [0, 0.4, 0.7],    // Dark blue
    [0, 0.2, 0.5]     // Deep blue
  ],
  
  forest: [
    [0.6, 1, 0.2],    // Light green
    [0.4, 0.8, 0.2],  // Medium green
    [0.2, 0.6, 0.1],  // Dark green
    [0.1, 0.4, 0.05]  // Deep green
  ]
};

// Apply palette to shapes
const applyPalette = (shapes, palette) => {
  return shapes.map((shape, index) => {
    const colorIndex = index % palette.length;
    return colorize(palette[colorIndex], shape);
  });
};

Color Analysis

Analyze and manipulate colors:

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

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

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

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

// Usage
const baseColor = [0.8, 0.2, 0.2]; // Dark red
const brighter = adjustBrightness(baseColor, 1.5);
const desaturated = adjustSaturation(baseColor, 0.5);
const complement = getComplementaryColor(baseColor);

Manufacturing Color Considerations

Consider color requirements for different manufacturing processes:

const { colorize, rgbToHex } = require('@jscad/modeling').colors;

// 3D printing color validation
const validatePrintingColor = (rgb) => {
  // Check if color is too light for visibility
  const luminance = 0.299 * rgb[0] + 0.587 * rgb[1] + 0.114 * rgb[2];
  if (luminance > 0.9) {
    console.warn('Color may be too light for 3D printing visibility');
  }
  
  // Convert to hex for printing software
  const hex = rgbToHex(rgb);
  return { rgb, hex, luminance };
};

// CNC machining material colors
const machiningMaterials = {
  aluminum: [0.9, 0.9, 0.9],
  steel: [0.5, 0.5, 0.5],
  brass: [0.8, 0.7, 0.4],
  copper: [0.7, 0.4, 0.2]
};

const applyMaterialColor = (shape, material) => {
  if (machiningMaterials[material]) {
    return colorize(machiningMaterials[material], shape);
  }
  throw new Error(`Unknown material: ${material}`);
};

docs

booleans.md

colors.md

curves.md

expansions-modifiers.md

extrusions.md

geometries.md

hulls.md

index.md

maths.md

measurements.md

primitives.md

text-utils.md

transforms.md

tile.json