isometric-ops

Files (30)

• SKILL.md
• blender-iso-rig.py · assets/
• dimetric-2to1-128.svg · assets/grids/
• dimetric-2to1-32.svg · assets/grids/
• dimetric-2to1-64.svg · assets/grids/
• true-iso-128.svg · assets/grids/
• true-iso-32.svg · assets/grids/
• true-iso-64.svg · assets/grids/
• three-tone-presets.json · assets/palettes/
• prompt-library.md · assets/
• ai-generation.md · references/
• ai-refinement.md · references/
• asset-sourcing.md · references/
• blender-prerender.md · references/
• coordinates-depth.md · references/
• css-isometric.md · references/
• engine-integration.md · references/
• iso-studio.md · references/
• pixel-art-workflow.md · references/
• projection-math.md · references/
• style-guide.md · references/
• svg-vector-generation.md · references/
• task-routes.md · references/
• threejs-orthographic.md · references/
• tile-spec.md · references/
• check-iso-facts.py · scripts/
• iso-math.py · scripts/
• sheet-pack.py · scripts/
• tile-validate.py · scripts/
• run.sh · tests/

SKILL.md (first lines)

# Isometric Operations

Create, refine, compose, and export isometric illustrative assets for websites and
games — end to end. This skill covers the exact projection math, the vector/CSS/SVG and
three.js generation routes, the pixel-art and Blender pre-render pipelines, engine
tilemap integration, the AI-generation-with-structure-control workflow, asset sourcing
with licence discipline, and the companion **iso-studio** scene composer (a standalone
app that grew out of this skill). Every constant is
derived and machine-checked; every workflow is runnable; every claim is sourced in its
reference file.

> **Boundary — what this skill does NOT own.** General three.js / creative-coding
> scaffolding lives in [`genart-ops`](../genart-ops/SKILL.md); app- and game-scale
> three.js (GLTF pipeline, react-three-fiber, `InstancedMesh`) lives in the `threejs-ops`
> skill. Colour science and perceptual (OKLCH) ramp construction live in
> [`color-ops`](../color-ops/SKILL.md). `isometric-ops` owns **only the isometric delta**
> — it cross-links those siblings, it never restates them. Detail lives in the reference
> files below: this router points, it does not duplicate.

---

## 1. The projection decision — always step zero

Choose the projection **before** you draw, generate, or model anything. This is not a
deferrable stylistic preference: it fixes the grid math, the tile aspect ratio, the
camera rig, and the anti-aliasing strategy for the entire pipeline downstream. Changing
it later means re-cutting every asset.

| Job | Projection | Ground-axis angle | Tile / face rule | Where |
|---|---|---|---|---|
| Web / vector illustration, diagrams, icons, hero art | **True isometric** | **30°** (all three axes 120° apart) | all axes foreshorten equally; smooth vector edges ignore pixel stepping | [`projection-math.md`](references/projection-math.md) §1, [`svg-vector-generation.md`](references/svg-vector-generation.md), [`css-isometric.md`](references/css-isometric.md) |
| Game tiles, tilemaps, sprite worlds, most "isometric" games | **2:1 dimetric** (commonly called isometric in games) | **26.565°** = arctan(1/2) | integer 2px:1px steps tessellate; `tileW = 2·tileH` | [`projection-math.md`](references/projection-math.md) §2, [`coordinates-depth.md`](references/coordinates-depth.md), [`engine-integration.md`](references/engine-integration.md) |
| Hand-placed / library pixel-art primitives (cubes, bricks, slopes) | **Pixel-neat 1:2** | **22.6°** (obelisk.js pixel-dot pattern) | 1:2 pixel dot stepping avoids staircasing at primitive-drawing level | [`projection-math.md`](references/projection-math.md) §7, [`pixel-art-workflow.md`](references/pixel-art-workflow.md) |

**The failure mode this prevents.** Nearly every "isometric" game is actually
**dimetric** (only two of the three axis separations are equal: ≈116.565°, 116.565°,
126.870°). The trap: an artist draws a "30° isometric" tile, the engine places it on a
2:1 (26.565°) diamond grid, and **the tile edges do not meet their neighbours**. Small at
one tile, catastrophic across a 50×50 map. The fix is not a nudge tool — it is deciding,
up front, that game tiles are **2:1 dimetric at 26.565°** and writing that number into
the [tile spec](references/tile-spec.md) so every asset is cut to the same grid.

**Terminology discipline (applies everywhere).** On first use per document write
**"2:1 dimetric (commonly called isometric in games)"**, then "2:1 dimetric" thereafter.
Never call the 2:1 game projection "isometric" unqualified. Distinguish **"isometric
drawing"** (100% scale) from **"isometric projection"** (81.65% = √(2/3) scale) whenever
the distinction affects a measurement.

### Canonical constants (the authority table)

Machine-emitted by [`iso-math.py constants`](scripts/iso-math.py); full derivations and
ground-truth checks in [`projection-math.md`](references/projection-math.md).

| Symbol | Exact form | Value | Appears as |
|---|---|---|---|
| Cube tilt ("magic angle") | `arctan(1/√2) = arcsin(1/√3)` | **35.264°** | 3D iso rotation |
| Foreshortening (projection scale) | `cos(35.264°) = √(2/3)` | **81.65%** (0.81650) | true-projection edge scale |
| Isometric **drawing** scale | full-scale convention | **100%** | vector iso (edges read at 100%) |
| True ground angle | definition | **30°** | vector iso axes |
| SSR / top-plane squash | `cos(30°)` | **86.602%** (0.86603) | Illustrator scale, 2D plane matrices |
| Figma height / circle→ellipse | `tan(30°)` | **57.735%** (0.57735) | Figma hack, ellipse minor axis |
| CSS back-tip | `arctan(√2) = 90° − 35.264°` | **54.7356°** | CSS `rotateX` |
| CSS un-foreshorten | `√(3/2) = 1/cos(35.264°)` | **1.22474** | CSS `scale3d` |
| Dimetric ground angle | `arctan(1/2)` | **26.565°** | game tiles |
| Dimetric screen slope | `tileH/tileW` (2:1) | **0.5** | tile-space `+x` = `(+tileW/2, +tileH/2)` |

> Two Blender ortho-camera rigs, both must appear wherever rigs are discussed: **2:1
> dimetric = RotX 60°, RotY 0°, RotZ 45°** (cube top 2× wide as tall, `sin 30° = 0.5`);
> **true isometric = RotX 54.736°, RotY 0°, RotZ 45°** (all three faces equal). Most
> tutorials use 60/0/45 and mislabel it "isometric" — it is dimetric. See
> [`blender-prerender.md`](references/blender-prerender.md) §1.

---

## 2. Task router — six routes

Each route is a numbered mini-workflow. Follow the links for the exact numbers, code, and
gotchas — the steps here are the spine, the references are the flesh.

### Route A — Illustrate for the web (vector / CSS / SVG)

For diagrams, icons, hero art, marketing scenes → **true isometric (30°)**.

1. **Decide** true iso (§1). Pin the light direction and palette up front
   ([`style-guide.md`](references/style-guide.md)).
2. **Pick the medium.** Live DOM elements you want selectable / accessible / SEO-visible →
   CSS. Static shapes and icon sets → SVG. See the decision tables in
   [`css-isometric.md`](references/css-isometric.md) and
   [`svg-vector-generation.md`](references/svg-vector-generation.md).
3. **CSS route.** 3D: `transform-style: preserve-3d` on the container, per-face children,
   then the outer stack `rotateX(54.7356deg) rotateZ(-45deg) scale3d(1.22474,…)` — the
   scale goes on the container **only** (or faces double-scale). 2D affine for flat cards:
   the `rotate(-30deg) skewX(30deg) scaleY(0.866)` recipe family, derived per plane in
   [`css-isometric.md`](references/css-isometric.md).
4. **SVG route.** Reach for [`@elchininet/isometric`](references/svg-vector-generation.md)
   (SVG-native, planes/paths) or hand-roll diamond/cube/prism paths using the plane
   `matrix()` recipes (Top `matrix(0.86603, 0.5, 0.86603, -0.5, 0, 0)`, etc.). Grab a
   ready grid from [`assets/grids/`](assets/grids/) or emit one with
   `iso-math.py grid-svg`.
5. **Optimise & export.** Simplify paths in-tool → export → SVGO/SVGOMG → raster
   derivatives, **in that order** ([`svg-vector-generation.md`](references/svg-vector-generation.md) §7).
6. **Verify visually.** For map-heavy web work, headless-screenshot checks belong to
   [`playwright-ops`](../playwright-ops/SKILL.md); tie the render back to the
   [style checklist](references/style-guide.md).

### Route B — Build a game tileset (spec → generate → validate → pack → engine)

For tilemaps and sprite worlds → **2:1 dimetric (26.565°)**. This is the discipline route;
skipping the spec is how sets drift.

1. **Write the spec first.** Copy the fill-in template from
   [`tile-spec.md`](references/tile-spec.md) and pin: projection + exact angle, tile W×H
   (`W = 2H`), unit elevation (px per z-step), anchor **at the feet**, footprint grammar
   (1×1, 2×1, 2×2…), transparent margin/bleed, palette tokens, one light direction, output
   format, `name_direction_variant.png` naming, and scale grammar (one human = N tiles).
2. **Generate** the tiles — draw them ([`pixel-art-workflow.md`](references/pixel-art-workflow.md)),
   pre-render from 3D (Route D), or AI-generate (Route C). Every asset obeys the spec's
   numbers.
3. **Validate** each tile against the spec:

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods