figureone 1.9.0 → 1.10.0

package/llms-full.txt

@@ -115,6 +115,8 @@ Path to figure element(s) within a collection. Supports multiple formats:
 | loadColor | TypeColor | `[0, 0, 1, 0.5]` | Color while loading |
 | onLoad | () => void | | Callback after load |
 
+A `texture` on the `gl` primitive can be recolored by region with one or more masks — see OBJ_TextureMask under OBJ_GenericGL.
+
 ### OBJ_FigurePrimitive (base for all primitives)
 
 | Property | Type | Default | Description |
@@ -365,12 +367,47 @@ Extends OBJ_Generic (without drawType).
 | attributes | OBJ_GLAttribute[] | | Shader attributes |
 | uniforms | OBJ_GLUniform[] | | Shader uniforms |
 | texture | OBJ_Texture | | Texture |
+| mask | OBJ_TextureMask | | Single mask to recolor regions of `texture` |
+| masks | OBJ_TextureMask[] | | Multiple masks (each adds 4 recolorable regions) |
+| tints | (TypeColor \| null)[] | | Recolor per region; mask `m` uses `tints[4m]`…`tints[4m+3]` for its r,g,b,a channels (`null` = leave region unchanged) |
 | dimension | `2` \| `3` | `2` | Coordinate dimensions |
 | light | `'directional'` \| `'point'` \| null | null | Lighting |
 | vertices | number[] \| object | | Vertex data |
 | colors | number[] \| object | | Per-vertex colors |
 | normals | number[] \| object | | Normal vectors |
 
+A texture can be recolored by region using one or more masks. A mask shares the base texture's coordinates (same dimensions, aligned to the base image); each of its r, g, b, a channels marks a region. Mask `m` is recolored by `tints[4m]` (r), `tints[4m + 1]` (g), `tints[4m + 2]` (b), `tints[4m + 3]` (a); unmasked pixels keep the base texture's color. A single mask costs one extra texture fetch and four mixes; each additional mask adds one fetch and four mixes.
+
+### OBJ_TextureMask
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| src | string | | URL of the mask image |
+| loadColor | TypeColor | `[0, 0, 0, 0]` | Color shown while the mask loads (transparent = nothing recolored until loaded) |
+
+```js
+// Recolor three regions of a texture with one mask. The mask image's red,
+// green and blue channels mark the regions tinted by tints 0, 1 and 2.
+figure.add({
+  make: 'gl',
+  vertices: [-0.8, -0.8, 0.8, -0.8, -0.8, 0.8, 0.8, -0.8, 0.8, 0.8, -0.8, 0.8],
+  texture: { src: './image.png', coords: [0, 0, 1, 0, 0, 1, 1, 0, 1, 1, 0, 1] },
+  mask: { src: './mask.png' },
+  tints: [[1, 0, 0, 1], [0, 0.6, 0, 1], [0, 0, 1, 1]],
+});
+
+// Two masks: mask 0 uses tints 0-3, mask 1 uses tints 4-7.
+figure.add({
+  make: 'gl',
+  // ...vertices, texture...
+  masks: [{ src: './mask.png' }, { src: './mask1.png' }],
+  tints: [
+    [1, 0, 0, 1], [0, 0.6, 0, 1], [0, 0, 1, 1], null, // mask 0
+    [0.6, 0, 0.8, 1],                                 // mask 1
+  ],
+});
+```
+
 ### OBJ_Morph (`make: 'morph'`)
 
 Morphable shape with multiple point arrays that can be animated between.
@@ -523,6 +560,39 @@ const points = Fig.surfaceGrid({
 figure.add({ make: 'surface', points, color: [1, 0, 0, 1], normals: 'curve' });
 ```
 
+### OBJ_RotateControl (`make: 'rotateControl'`)
+
+Rotates a 3D element with drag gestures. Produces the same on-screen motion as
+`cameraControl`, but rotates the object instead of orbiting the camera — so the
+world-fixed lights shade the object differently as it turns.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| left | number | `0` | Screen left (0-1) |
+| bottom | number | `0` | Screen bottom (0-1) |
+| width | number | `1` | Width (0-1) |
+| height | number | `1` | Height (0-1) |
+| axis | TypeParsablePoint | `[0, 1, 0]` | Vertical axis |
+| controlElement | FigureElement \| string | | Element to rotate (required; must not be an ancestor of the control) |
+| sensitivity | number | `5` | Overall sensitivity |
+| xSensitivity | number | `1` | Horizontal sensitivity (0 = no azimuth) |
+| ySensitivity | number | `1` | Vertical sensitivity (0 = no elevation) |
+| back | boolean | `false` | If true, other touchable elements are touched first (object rotates only on empty-space drags) |
+
+```js
+const figure = new Fig.Figure({
+  scene: {
+    style: 'orthographic',
+    near: 0.1,
+    far: 10,
+    camera: { position: [1, 0.6, 1.5], lookAt: [0, 0, 0], up: [0, 1, 0] },
+    light: { directional: [0.7, 0.5, 1], ambient: 0.4 },
+  },
+});
+const cube = figure.add({ make: 'cube', side: 0.6, color: [1, 0, 0, 1], light: 'directional' });
+figure.add({ make: 'rotateControl', controlElement: cube });
+```
+
 ---
 
 ## 5. Collections

package/llms.txt

@@ -63,6 +63,7 @@ Other `Fig.Figure` options: `textStyle` (`'italic'` default | `'normal'` — def
 | `prism` | 3D prism |
 | `revolve` | 3D surface of revolution |
 | `cameraControl` | Enables 3D camera rotation via drag |
+| `rotateControl` | Rotates a 3D element via drag (object turns, camera/light fixed); set `controlElement` |
 
 Shorthand `make: 'polygon'` is equivalent to `make: 'primitives.polygon'`.
 
@@ -97,6 +98,16 @@ figure.add({
   make: 'rectangle', width: 1.8, height: 1.2,
   texture: { src: 'image.jpg', mapTo: [-0.9, -0.6, 1.8, 1.2] },
 });
+
+// Recolor regions of a texture with masks (gl primitive). Each mask's r,g,b,a
+// channels mark regions; mask m is tinted by tints[4m]..tints[4m+3].
+figure.add({
+  make: 'gl',
+  vertices: [-0.8, -0.8, 0.8, -0.8, -0.8, 0.8, 0.8, -0.8, 0.8, 0.8, -0.8, 0.8],
+  texture: { src: 'image.png', coords: [0, 0, 1, 0, 0, 1, 1, 0, 1, 1, 0, 1] },
+  masks: [{ src: 'mask.png' }, { src: 'mask1.png' }],
+  tints: [[1, 0, 0, 1], [0, 0.6, 0, 1], [0, 0, 1, 1], null, [0.6, 0, 0.8, 1]],
+});
 ```
 
 ### Element Properties

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figureone",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Draw, animate and interact with shapes, text, plots and equations in Javascript. Create interactive slide shows, and interactive videos.",
   "main": "index.js",
   "types": "types/index.d.ts",

package/types/js/figure/FigurePrimitives/FigurePrimitiveTypes3D.d.ts

@@ -2,6 +2,7 @@ import type { TypeGLBufferUsage } from '../DrawingObjects/GLObject/GLObject';
 import type { CPY_Step } from '../geometries/copy/copy';
 import type { TypeParsablePoint } from '../../tools/geometry/Point';
 import type Scene from '../../tools/geometry/scene';
+import type { FigureElement } from '../Element';
 import type { TypeColor } from '../../tools/types';
 import type { TypeParsableLine } from '../../tools/geometry/Line';
 import type { OBJ_Line3Arrow } from '../../tools/d3/line3';
@@ -1103,3 +1104,94 @@ export type OBJ_CameraControl = {
     ySensitivity?: number;
     back?: boolean;
 } & OBJ_FigurePrimitive;
+/**
+ * Rotate control definition object that extends {@link OBJ_FigurePrimitive}.
+ *
+ * A rotate control is a transparent rectangle that uses touch and drag gestures
+ * to rotate a 3D element. It produces the same on-screen motion as
+ * {@link OBJ_CameraControl}, but rotates the *object* rather than orbiting the
+ * camera. Because the scene lights are fixed in world space, the object's faces
+ * are shaded differently as it turns (with `cameraControl` the shading stays
+ * fixed relative to the object).
+ *
+ * Left/right movements rotate the object around the vertical `axis` (azimuth),
+ * while up/down movements change its elevation relative to that axis.
+ *
+ * The transparent rectangle is positioned relative to the 2D HTML canvas. The
+ * `left`, `bottom`, `width` and `height` properties are numbers from 0 to 1
+ * representing a percentage of the screen width and height. For the rectangle to
+ * cover the entire screen use `left: 0`, `bottom: 0`, `width: 1`, `height: 1`
+ * (the defaults).
+ *
+ * Set `controlElement` (by name or reference) to the element to rotate. This is
+ * required - it must not be an ancestor of the control (e.g. its parent
+ * collection), otherwise rotating it would corrupt the control's own gesture
+ * coordinates. With no `controlElement` the control does nothing. The element
+ * should be centered on its scene's camera `lookAt` point so that it spins in
+ * place.
+ *
+ * @property {number} [left] screen left position to place the control rectangle.
+ * 0 is the left edge, while 1 is the right edge (`0`).
+ * @property {number} [bottom] screen bottom position to place the control
+ * rectangle. 0 is the bottom edge, while 1 is the top edge (`0`).
+ * @property {number} [width] width of control rectangle. 1 is the full width of
+ * the drawing canvas (`1`).
+ * @property {number} [height] height of control rectangle. 1 is the full height
+ * of the drawing canvas (`1`).
+ * @property {TypeParsablePoint} [axis] axis to keep vertical as the object is
+ * rotated. The axis vector and scene.camera.up vector should be in the same
+ * plane (`[0, 1, 0]`)
+ * @property {FigureElement | string} [controlElement] element to rotate (by name
+ * or reference). Required; must not be an ancestor of the control. With no value
+ * the control does nothing.
+ * @property {number} [sensitivity] sensitivity of object rotation relative to
+ * user movement where larger numbers result in more rotation for the same
+ * movement (`5`)
+ * @property {number} [xSensitivity] sensitivity to a horizontal user movement.
+ * Setting this to 0 will mean the object does not rotate azimuthally (`1`)
+ * @property {number} [ySensitivity] sensitivity to a vertical user movement.
+ * Setting this to 0 will mean the elevation does not change (`1`)
+ * @property {boolean} [back] if `false` (the default) the control captures all
+ * drags, so dragging the object (or anywhere) rotates it. If `true`, all 2D and
+ * 3D objects that can be touched are touched before the rotate control, so the
+ * object only rotates when dragging empty space - use this when other elements
+ * also need to be interactive (`false`)
+ *
+ * @example
+ * // Cube that can be rotated by dragging anywhere on the figure.
+ * // Set the 3D scene in the constructor so figure.scene and
+ * // figure.elements.scene are wired consistently.
+ * const figure = new Fig.Figure({
+ *   scene: {
+ *     style: 'orthographic',
+ *     near: 0.1,
+ *     far: 10,
+ *     camera: { position: [1, 0.6, 1.5], lookAt: [0, 0, 0], up: [0, 1, 0] },
+ *     light: { directional: [0.7, 0.5, 1], ambient: 0.4 },
+ *   },
+ * });
+ *
+ * const cube = figure.add({
+ *   make: 'cube',
+ *   side: 0.6,
+ *   color: [1, 0, 0, 1],
+ *   light: 'directional',
+ * });
+ *
+ * figure.add({ make: 'rotateControl', controlElement: cube });
+ *
+ * @interface
+ * @group Interactivity
+ */
+export type OBJ_RotateControl = {
+    left?: number;
+    bottom?: number;
+    width?: number;
+    height?: number;
+    axis?: TypeParsablePoint;
+    controlElement?: FigureElement | string;
+    sensitivity?: number;
+    xSensitivity?: number;
+    ySensitivity?: number;
+    back?: boolean;
+} & OBJ_FigurePrimitive;

package/types/js/figure/FigurePrimitives/FigurePrimitives.d.ts

@@ -13,7 +13,7 @@ import FigureElementPrimitiveGesture from './FigureElementPrimitiveGesture';
 import type { OBJ_Gesture } from './FigureElementPrimitiveGesture';
 import type { OBJ_LineStyleSimple, OBJ_GenericGL, OBJ_Morph, OBJ_Text } from './FigurePrimitiveTypes';
 import type { OBJ_Generic, OBJ_Polyline, OBJ_Polygon, OBJ_Polygon_Defined, OBJ_Star, OBJ_Rectangle, OBJ_Ellipse, OBJ_Arc, OBJ_Triangle, OBJ_Line, OBJ_Grid, OBJ_Arrow } from './FigurePrimitiveTypes2D';
-import type { OBJ_Generic3, OBJ_Sphere, OBJ_Cube, OBJ_Cylinder, OBJ_Cone, OBJ_Revolve, OBJ_Surface, OBJ_Line3, OBJ_CameraControl, OBJ_Prism } from './FigurePrimitiveTypes3D';
+import type { OBJ_Generic3, OBJ_Sphere, OBJ_Cube, OBJ_Cylinder, OBJ_Cone, OBJ_Revolve, OBJ_Surface, OBJ_Line3, OBJ_CameraControl, OBJ_RotateControl, OBJ_Prism } from './FigurePrimitiveTypes3D';
 type OBJ_PolyLineTris = OBJ_LineStyleSimple & {
     drawBorderBuffer: number | Array<Array<Point>>;
 };
@@ -106,6 +106,18 @@ export default class FigurePrimitives {
      * @see {@link OBJ_CameraControl} for options and examples.
      */
     cameraControl(...options: Array<OBJ_CameraControl>): any;
+    /**
+     * {@link FigureElementPrimitive} that rotates a 3D element with touch and drag
+     * gestures.
+     *
+     * This produces the same on-screen motion as {@link OBJ_CameraControl}, but
+     * rotates the *object* instead of orbiting the camera. As the scene's lights
+     * are fixed in world space, the object's faces are shaded differently as it
+     * turns (with `cameraControl` the shading stays fixed relative to the object).
+     *
+     * @see {@link OBJ_RotateControl} for options and examples.
+     */
+    rotateControl(...options: Array<OBJ_RotateControl>): any;
     /**
      * {@link FigureElementPrimitive} that draws an ellipse.
      * @see {@link OBJ_Ellipse} for options and examples.