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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Transformations

Name: tessl/npm-jscad--modeling
Author: tessl

All shapes (primitives or the results of operations) can be transformed, such as scaled or rotated. In all cases, the functions return new results and never change the original shapes. Transformations use a right-handed coordinate system with consistent mathematical conventions.

Capabilities

Translation

Move shapes to new positions in 2D or 3D space.

/**
 * Translate geometries by the given offsets
 * @param {Array} offsets - [x,y] for 2D or [x,y,z] for 3D translation
 * @param {...Object} objects - Objects to translate
 * @returns {Object|Array} Translated object(s)
 */
function translate(offsets: [number, number] | [number, number, number], ...objects: any[]): any;

/**
 * Translate geometries along the X axis
 * @param {Number} offset - Distance to translate along X axis
 * @param {...Object} objects - Objects to translate
 * @returns {Object|Array} Translated object(s)
 */
function translateX(offset: number, ...objects: any[]): any;

/**
 * Translate geometries along the Y axis  
 * @param {Number} offset - Distance to translate along Y axis
 * @param {...Object} objects - Objects to translate
 * @returns {Object|Array} Translated object(s)
 */
function translateY(offset: number, ...objects: any[]): any;

/**
 * Translate geometries along the Z axis
 * @param {Number} offset - Distance to translate along Z axis
 * @param {...Object} objects - Objects to translate
 * @returns {Object|Array} Translated object(s)
 */
function translateZ(offset: number, ...objects: any[]): any;

Usage Examples:

const { cube, sphere, translate, translateX, translateY, translateZ } = require('@jscad/modeling');

// 3D translation
const myCube = cube({ size: 10 });
const movedCube = translate([5, 10, 15], myCube);

// Individual axis translations
const sphere1 = sphere({ radius: 3 });
const movedRight = translateX(10, sphere1);
const movedUp = translateY(5, sphere1);  
const movedForward = translateZ(-8, sphere1);

// Multiple objects
const objects = [cube({ size: 5 }), sphere({ radius: 3 })];
const allMoved = translate([0, 0, 10], ...objects);

Rotation

Rotate shapes around axes or arbitrary vectors.

/**
 * Rotate geometries by the given angles
 * @param {Array|Number} angles - [x,y,z] angles in radians, or single angle for Z rotation
 * @param {...Object} objects - Objects to rotate  
 * @returns {Object|Array} Rotated object(s)
 */
function rotate(angles: [number, number, number] | number, ...objects: any[]): any;

/**
 * Rotate geometries around the X axis
 * @param {Number} angle - Angle in radians
 * @param {...Object} objects - Objects to rotate
 * @returns {Object|Array} Rotated object(s)
 */
function rotateX(angle: number, ...objects: any[]): any;

/**
 * Rotate geometries around the Y axis
 * @param {Number} angle - Angle in radians  
 * @param {...Object} objects - Objects to rotate
 * @returns {Object|Array} Rotated object(s)
 */
function rotateY(angle: number, ...objects: any[]): any;

/**
 * Rotate geometries around the Z axis
 * @param {Number} angle - Angle in radians
 * @param {...Object} objects - Objects to rotate
 * @returns {Object|Array} Rotated object(s)
 */
function rotateZ(angle: number, ...objects: any[]): any;

Usage Examples:

const { cube, cylinder, rotate, rotateX, rotateY, rotateZ } = require('@jscad/modeling');

// Rotate around multiple axes
const myCube = cube({ size: 10 });
const rotatedCube = rotate([Math.PI/4, Math.PI/6, Math.PI/3], myCube);

// Single axis rotations  
const myCylinder = cylinder({ height: 20, radius: 5 });
const sidewaysCylinder = rotateY(Math.PI/2, myCylinder);

// 2D rotation (Z axis)
const { rectangle } = require('@jscad/modeling').primitives;
const rect = rectangle({ size: [10, 5] });
const rotatedRect = rotateZ(Math.PI/4, rect);

Scaling

Scale shapes by factors along each axis.

/**
 * Scale geometries by the given factors  
 * @param {Array|Number} factors - [x,y,z] scale factors, [x,y] for 2D, or single factor for uniform scaling
 * @param {...Object} objects - Objects to scale
 * @returns {Object|Array} Scaled object(s)
 */
function scale(factors: [number, number, number] | [number, number] | number, ...objects: any[]): any;

/**
 * Scale geometries along the X axis
 * @param {Number} factor - Scale factor for X axis
 * @param {...Object} objects - Objects to scale
 * @returns {Object|Array} Scaled object(s)
 */
function scaleX(factor: number, ...objects: any[]): any;

/**
 * Scale geometries along the Y axis
 * @param {Number} factor - Scale factor for Y axis
 * @param {...Object} objects - Objects to scale  
 * @returns {Object|Array} Scaled object(s)
 */
function scaleY(factor: number, ...objects: any[]): any;

/**
 * Scale geometries along the Z axis
 * @param {Number} factor - Scale factor for Z axis
 * @param {...Object} objects - Objects to scale
 * @returns {Object|Array} Scaled object(s)
 */
function scaleZ(factor: number, ...objects: any[]): any;

Usage Examples:

const { cube, sphere, scale, scaleX, scaleY, scaleZ } = require('@jscad/modeling');

// Uniform scaling
const myCube = cube({ size: 10 });
const biggerCube = scale(2, myCube);
const smallerCube = scale(0.5, myCube);

// Non-uniform scaling
const mySphere = sphere({ radius: 5 });  
const ellipsoid = scale([2, 1, 0.5], mySphere);

// Individual axis scaling
const stretched = scaleX(3, myCube);
const flattened = scaleZ(0.1, myCube);

Mirroring

Mirror shapes across planes or axes.

/**
 * Mirror geometries across a plane
 * @param {Array} plane - [a,b,c,d] plane equation coefficients  
 * @param {...Object} objects - Objects to mirror
 * @returns {Object|Array} Mirrored object(s)
 */
function mirror(plane: [number, number, number, number], ...objects: any[]): any;

/**
 * Mirror geometries across the YZ plane (X=0)
 * @param {...Object} objects - Objects to mirror
 * @returns {Object|Array} Mirrored object(s)
 */
function mirrorX(...objects: any[]): any;

/**
 * Mirror geometries across the XZ plane (Y=0)  
 * @param {...Object} objects - Objects to mirror
 * @returns {Object|Array} Mirrored object(s)
 */
function mirrorY(...objects: any[]): any;

/**
 * Mirror geometries across the XY plane (Z=0)
 * @param {...Object} objects - Objects to mirror
 * @returns {Object|Array} Mirrored object(s)
 */
function mirrorZ(...objects: any[]): any;

Usage Examples:

const { cube, cylinder, mirror, mirrorX, mirrorY, mirrorZ, translate } = require('@jscad/modeling');

// Mirror across coordinate planes
const rightCube = translate([10, 0, 0], cube({ size: 5 }));
const leftCube = mirrorX(rightCube);

// Mirror across custom plane
const myCylinder = cylinder({ height: 10, radius: 3 });
const customPlane = [1, 1, 0, 0]; // Plane through origin with normal [1,1,0]
const mirroredCylinder = mirror(customPlane, myCylinder);

// Create symmetric objects
const { union } = require('@jscad/modeling').booleans;
const rightHalf = translate([5, 0, 0], cube({ size: [10, 5, 5] }));
const symmetric = union(rightHalf, mirrorX(rightHalf));

Centering and Alignment

Center shapes at the origin or align them to specific positions.

/**
 * Center geometries at the origin
 * @param {...Object} objects - Objects to center
 * @returns {Object|Array} Centered object(s)
 */
function center(...objects: any[]): any;

/**
 * Center geometries along the X axis
 * @param {...Object} objects - Objects to center on X axis
 * @returns {Object|Array} Centered object(s)
 */
function centerX(...objects: any[]): any;

/**
 * Center geometries along the Y axis
 * @param {...Object} objects - Objects to center on Y axis  
 * @returns {Object|Array} Centered object(s)
 */
function centerY(...objects: any[]): any;

/**
 * Center geometries along the Z axis
 * @param {...Object} objects - Objects to center on Z axis
 * @returns {Object|Array} Centered object(s)
 */
function centerZ(...objects: any[]): any;

/**
 * Align geometries to specific positions relative to their bounding boxes
 * @param {Object} options - Alignment options
 * @param {String} [options.modes=['center','center','min']] - Alignment modes per axis
 * @param {Array} [options.relativeTo] - Reference geometry for relative alignment
 * @param {...Object} objects - Objects to align
 * @returns {Object|Array} Aligned object(s)
 */
function align(options: {
  modes?: string[],
  relativeTo?: any
}, ...objects: any[]): any;

Usage Examples:

const { cube, sphere, center, centerX, align, translate } = require('@jscad/modeling');

// Center objects at origin
const offCenterCube = translate([10, 5, 3], cube({ size: 8 }));
const centeredCube = center(offCenterCube);

// Center only on specific axes  
const partialCenter = centerX(offCenterCube);

// Advanced alignment
const referenceCube = cube({ size: 10 });
const smallCube = cube({ size: 3 });

// Align small cube to corner of reference cube
const aligned = align(
  { modes: ['min', 'min', 'max'], relativeTo: referenceCube },
  smallCube
);

Matrix Transformations

Apply custom 4x4 transformation matrices for complex transformations.

/**
 * Transform geometries using a 4x4 transformation matrix
 * @param {Array} matrix - 4x4 transformation matrix (16 elements in column-major order)
 * @param {...Object} objects - Objects to transform
 * @returns {Object|Array} Transformed object(s)
 */
function transform(matrix: mat4, ...objects: any[]): any;

Usage Examples:

const { cube, transform, mat4 } = require('@jscad/modeling');

// Create custom transformation matrix
const { maths } = require('@jscad/modeling');
const customMatrix = maths.mat4.create();

// Combine rotation and translation
maths.mat4.rotateZ(customMatrix, customMatrix, Math.PI/4);
maths.mat4.translate(customMatrix, customMatrix, [10, 5, 0]);

const myCube = cube({ size: 5 });
const transformedCube = transform(customMatrix, myCube);

// Complex transformation combining multiple operations
const complexMatrix = maths.mat4.create();
maths.mat4.scale(complexMatrix, complexMatrix, [2, 1, 0.5]);
maths.mat4.rotateY(complexMatrix, complexMatrix, Math.PI/6);
maths.mat4.translate(complexMatrix, complexMatrix, [0, 0, 10]);

const complexTransform = transform(complexMatrix, myCube);

Advanced Transformation Techniques

Chaining Transformations

Transformations can be chained to create complex positioning:

const { cube, translate, rotate, scale, mirrorX } = require('@jscad/modeling');

const baseCube = cube({ size: 5 });

// Chain multiple transformations
const finalCube = translate([10, 0, 0],
  rotate([0, Math.PI/4, 0],
    scale([2, 1, 1], baseCube)
  )
);

// Create arrays of transformed objects
const spacing = 15;
const cubes = [];
for (let i = 0; i < 5; i++) {
  const transformed = translate([i * spacing, 0, 0],
    rotate([0, 0, i * Math.PI/8], baseCube)
  );
  cubes.push(transformed);
}