npm package: @genart-dev/plugin-figure
Description: Figure drawing construction plugin for genart.dev — mannequins, proportions, gesture, head construction, landmarks
Author: genart.dev
Latest version: 0.2.0

# @genart-dev/plugin-figure

Figure drawing construction plugin for [genart.dev](https://genart.dev) — overlay mannequins, proportion grids, gesture lines, head construction, and anatomical landmarks on any sketch. All layers are non-destructive display guides. Includes MCP tools for AI-agent control.

Part of [genart.dev](https://genart.dev) — a generative art platform with an MCP server, desktop app, and IDE extensions.

## Install

```bash
npm install @genart-dev/plugin-figure
```

## Usage

```typescript
import figurePlugin from "@genart-dev/plugin-figure";
import { createDefaultRegistry } from "@genart-dev/core";

const registry = createDefaultRegistry();
registry.registerPlugin(figurePlugin);

// Or access individual layer types, renderers, and utilities
import {
  mannequinLayerType,
  proportionGridLayerType,
  gestureLayerType,
  headLayerType,
  landmarksLayerType,
  figureMcpTools,
  stickRenderer,
  beanRenderer,
  blocksRenderer,
  loomisRenderer,
  anatomyRenderer,
  PROPORTION_SYSTEMS,
  getProportionSystem,
  ESSENTIAL_LANDMARKS,
  FULL_LANDMARKS,
  DEFAULT_STANDING_POSE,
  BODY_25_KEYPOINTS,
  SKELETON_CONNECTIONS,
  computeExtraKeypoints,
  keypointsToPixels,
  interpolatePath,
} from "@genart-dev/plugin-figure";
```

## Test Render

![Figure layers montage](test-renders/figure-layers.png)

20-panel montage showing all layer types with variations:
- **Row 1**: Mannequin methods — stick, bean, blocks, loomis, anatomy
- **Row 2**: Proportion grids — toddler (4 heads), older child (6), ideal (8), heroic (8.5), fashion (9)
- **Row 3**: Head construction — Loomis 3/4, Loomis turned, Asaro planes, simple oval, Loomis nodded
- **Row 4**: Gesture line of action, gesture + rhythm curves, essential landmarks, full landmarks, combined layers

Source: [`test-renders/figure-layers.genart`](test-renders/figure-layers.genart). Regenerate with `bash test-renders/render.sh`.

## Layer Types (5)

| Layer Type | Type ID | Category | Description |
|------------|---------|----------|-------------|
| Figure Mannequin | `figure:mannequin` | guide | Full-body mannequin with 5 rendering methods |
| Proportion Grid | `figure:proportion-grid` | guide | Head-height division grid with anatomical landmarks |
| Gesture Line | `figure:gesture` | guide | Line of action + Reilly rhythm curves |
| Head Construction | `figure:head` | guide | Loomis/Asaro/simple head construction overlay |
| Figure Landmarks | `figure:landmarks` | guide | Anatomical landmark markers on a posed figure |

## Mannequin Methods

The mannequin layer supports 5 rendering methods, representing a progression from simple to complex:

| Method | Description |
|--------|-------------|
| `stick` | Stick figure — lines connecting joints. Fastest way to block in pose and proportions. |
| `bean` | Bean/gesture form — simplified torso as an organic bean shape connecting ribcage to pelvis, with cylindrical limbs. Good for capturing flow and weight. |
| `blocks` | Block mannequin — geometric box forms for head, ribcage, pelvis, and limb segments. Useful for understanding 3D volume and foreshortening. |
| `loomis` | Loomis-style construction — anatomically proportioned forms based on Andrew Loomis's figure construction method, with ribcage/pelvis egg shapes and proper joint articulation. |
| `anatomy` | Anatomical overlay — simplified muscle groups and skeletal landmarks over the pose. Shows major muscle masses (deltoids, pectorals, latissimus, quadriceps, etc.) for anatomical study. |

All methods share these display properties:

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `method` | select | `"bean"` | Rendering method |
| `keypoints` | string (JSON) | standing pose | BODY_25 keypoint positions |
| `proportionSystem` | select | `"ideal"` | Proportion system for sizing |
| `showJoints` | boolean | `true` | Show joint markers |
| `jointRadius` | number | `5` | Joint marker radius (2–15) |
| `showSymmetryLine` | boolean | `false` | Show vertical symmetry axis |
| `showCenterOfGravity` | boolean | `false` | Show center of gravity marker |
| `showRibcagePelvis` | boolean | `true` | Show ribcage/pelvis forms |
| `ribcageTilt` | number | `0` | Ribcage tilt in degrees (-45 to 45) |
| `pelvisTilt` | number | `0` | Pelvis tilt in degrees (-45 to 45) |
| `ribcageTwist` | number | `0` | Ribcage twist in degrees (-30 to 30) |
| `pelvisTwist` | number | `0` | Pelvis twist in degrees (-30 to 30) |
| `transparency` | number | `0.7` | Figure transparency (0–1) |

## Proportion Systems

Seven proportion systems for different figure types:

| System | Head Units | Use Case |
|--------|-----------|----------|
| `child-4` | 4 | Toddler proportions |
| `child-5` | 5 | Young child (ages ~4–6) |
| `child-6` | 6 | Older child (ages ~7–11) |
| `average` | 7.5 | Realistic average adult proportions |
| `ideal` | 8 | Classical ideal adult (default) |
| `heroic` | 8.5 | Heroic/superhero proportions |
| `fashion` | 9 | Fashion illustration elongated proportions |

Each system defines head-unit divisions, anatomical landmark positions (chin, nipple line, navel, crotch, knee), and body width ratios (shoulder, hip relative to head width).

## Anatomical Landmarks

Two landmark sets for marking surface-visible skeletal points:

**Essential (12 landmarks)** — the most important points for figure construction:
C7, Acromion (L/R), Xiphoid, ASIS (L/R), Greater Trochanter (L/R), Medial Epicondyle of Knee (L/R), Medial Malleolus (L/R)

**Full (28 landmarks)** — essential + 16 additional points:
Mastoid (L/R), Clavicle Head (L/R), Coracoid (L/R), Olecranon (L/R), Radial Styloid (L/R), Ulnar Styloid (L/R), Patella (L/R), Lateral Malleolus (L/R), Scapula Inferior Angle (L/R), Iliac Crest (L/R)

Each landmark is positioned relative to a BODY_25 joint keypoint with a normalized offset.

## Gesture Lines

The gesture layer draws two types of curves:

**Line of Action** — a single flowing curve that captures the primary thrust and rhythm of the pose. Drawn in red by default with optional taper (thick in the middle, thin at ends). Supports smooth, angular, or organic interpolation styles.

**Reilly Rhythm Curves** — secondary curves that describe the flow of major muscle groups and contours. Based on Frank Reilly's abstract rhythm analysis method. Each curve can have an optional label (e.g., "S-curve", "C-curve").

Both curve types use Catmull-Rom spline interpolation for smooth rendering.

## Head Construction

Three head construction methods:

| Method | Description |
|--------|-------------|
| `loomis` | Andrew Loomis ball-and-plane method — skull sphere with temporal side plane cut, jaw wedge, and feature proportion guidelines (hairline, brow, eye, nose, chin, ear). Full 3D tilt support. |
| `asaro` | Asaro head planes — simplified planar breakdown of the head into front, top, and side planes with cheek plane construction lines. Useful for understanding light and shadow. |
| `simple` | Basic egg/oval with optional cross-lines for quick head placement. |

All methods support 3-axis rotation: tiltX (nod, -60 to 60), tiltY (turn, -90 to 90), tiltZ (roll, -30 to 30).

## MCP Tools (8)

| Tool | Description |
|------|-------------|
| `add_figure_mannequin` | Add a mannequin layer (stick/bean/blocks/loomis/anatomy) with optional preset pose |
| `set_figure_pose` | Update joint positions and tilt/twist on an existing mannequin layer |
| `add_proportion_grid` | Add a proportion grid with head-height divisions and landmark labels |
| `add_gesture_line` | Add a gesture line (line of action + optional rhythm curves) |
| `add_head_construction` | Add a head construction overlay (Loomis/Asaro/simple) |
| `add_figure_landmarks` | Add anatomical landmark annotations to a posed figure |
| `generate_figure_from_description` | Generate mannequin from text description (e.g., "standing with arms raised") |
| `clear_figure_guides` | Remove all `figure:*` layers |

## BODY_25 Keypoint Compatibility

This plugin uses the BODY_25 keypoint format (25 keypoints: nose, neck, shoulders, elbows, wrists, hips, knees, ankles, eyes, ears, toes, heels), which is fully compatible with `@genart-dev/plugin-poses`. Pose keypoints from plugin-poses can be passed directly to any figure layer via the `keypoints` property.

The plugin also computes 8 additional construction keypoints derived from BODY_25 (ribcageCenter, pelvisCenter, c7, xiphoid, navelPoint, pubicSymphysis, scapula inferior angles) via `computeExtraKeypoints()`.

## Programmatic Example

```typescript
import { createCanvas } from "canvas";
import {
  mannequinLayerType,
  DEFAULT_STANDING_POSE,
} from "@genart-dev/plugin-figure";

const canvas = createCanvas(400, 600);
const ctx = canvas.getContext("2d");

const bounds = { x: 0, y: 0, width: 400, height: 600, rotation: 0, scaleX: 1, scaleY: 1 };
const resources = { getFont: () => null, getImage: () => null, theme: "dark", pixelRatio: 1 };

const props = {
  ...mannequinLayerType.createDefault(),
  method: "loomis",
  keypoints: JSON.stringify(DEFAULT_STANDING_POSE),
};

mannequinLayerType.render(props, ctx, bounds, resources);
```

## Related Packages

| Package | Purpose |
|---------|---------|
| [`@genart-dev/core`](https://github.com/genart-dev/core) | Plugin host, layer system (dependency) |
| [`@genart-dev/plugin-poses`](https://github.com/genart-dev/plugin-poses) | Pose estimation — provides BODY_25 keypoints for figure layers |
| [`@genart-dev/plugin-perspective`](https://github.com/genart-dev/plugin-perspective) | Perspective grids and floor planes |
| [`@genart-dev/mcp-server`](https://github.com/genart-dev/mcp-server) | MCP server that surfaces plugin tools to AI agents |

## Support

Questions, bugs, or feedback — [support@genart.dev](mailto:support@genart.dev) or [open an issue](https://github.com/genart-dev/plugin-figure/issues).

## License

MIT