# Object Study 1.1.1

A Three.js object viewer with **CMYK comic** shading: overlapping cyan, magenta, yellow, and black dots form the colors on white paper. Dots shrink to expose more paper in highlights and grow denser in shadows as the directional light moves. The palette defines the midtone ink colors; actual lighting and cast shadows drive the printed shading. The default controller has a teal casing, magenta touchpad, yellow buttons, and dark sticks. Bold black silhouettes and fine detail lines preserve the illustration look. Single-ink **Halftone**, stepped black-and-gray **Ink**, and unshaded **Line drawing** remain available. The controller is modeled entirely in code.

Try the interactive controls and download the component at [kraft.team/components/object-study](https://kraft.team/components/object-study/).

## Embed on a website

```html
<script defer src="https://kraft.team/components/assets/object-study/1.1.1/component.js"></script>
<object-study
  mode="cmyk"
  cmyk-base-color="#19bad0"
  cmyk-accent-color="#f25190"
  cmyk-button-color="#f6c832"
  dot-spacing="8"
  dot-size="1"
  dot-angle="0"
  shadow-coverage="0.18"
  light-azimuth="-21"
  light-elevation="35"
  style="display: block; width: 100%; height: 420px"
></object-study>
```

The bundle includes Three.js and registers `<object-study>`. It needs no framework, CDN imports, or separate model files. To host it yourself, copy `object-study.js` from the download and change the script URL. The element initializes when near the viewport and releases its renderer when removed. Drag to rotate, scroll to zoom, and right-drag to pan.

Set attributes initially or change them with `setAttribute()`:

| Attribute | Default | Values |
| --- | --- | --- |
| `mode` | `halftone` | `cmyk` (CMYK comic), `halftone`, `illustration` (Ink), `line` |
| `silhouette-weight` | `3.5` | 2–8 display pixels |
| `detail-weight` | `0.9` | 0.3–1.8 display pixels |
| `detail-level` | `62` | 0–85; higher reveals more creases |
| `details` | `true` | `true`, `false` |
| `shadow-steps` | `3` | 2–6; Ink mode |
| `shadow-coverage` | `0.28` | 0–0.8 |
| `dot-spacing` | `6` | 3–14 display pixels |
| `dot-size` | `1` | 0.4–1.4; 1 = 100% |
| `dot-angle` | `45` | 0–90 degrees |
| `base-color` | `#f6b744` | Three- or six-digit hex color |
| `ink-color` | `#000000` | Three- or six-digit hex color; Halftone mode |
| `cmyk-base-color` | `#19bad0` | Controller casing midtone color; CMYK mode |
| `cmyk-accent-color` | `#f25190` | Controller touchpad midtone color; CMYK mode |
| `cmyk-button-color` | `#f6c832` | Controller face-button midtone color; CMYK mode |
| `light-azimuth` | `-21` | −180–180 degrees |
| `light-elevation` | `35` | −85–85 degrees |
| `view` | `axonometric` | `axonometric`, `front`, `side`, `top` |

Numeric values are clamped to these ranges; invalid settings use their defaults. CMYK palette attributes accept three- or six-digit hex colors. Missing attributes keep the original element defaults; the website and standalone demo explicitly select the CMYK preset shown above. The element supports `resetView(view)`, `resetModel()`, `loadModel(file)` (an asynchronous boolean result), and `exportPNG()` (a Promise resolving to a Blob). Call these methods after `object-study-ready`. `object-study-ready` supplies `{ mode }`, `object-study-view-change` supplies `{ view }`, and `object-study-error` supplies `{ message }` in `event.detail`; all three events bubble across the element's shadow boundary.

## Standalone viewer and development

```sh
cd /home/ahmad/creativity/technical-object
npm install
npm run dev
```

Open `http://localhost:4174` on the machine running the server. On a remote host, forward port 4174 or open its reachable preview address. The viewer requires a browser with WebGL 2. Run `npm run build` to generate the standalone site, `dist/object-study.js`, a self-contained `dist/demo.html`, and the source download `dist/object-study-1.1.1.zip`. Use `npm run preview` to serve the built viewer.

Drag to rotate, scroll to zoom, and right-drag to pan. Choose the front, side, top, or three-quarter view. **CMYK comic** is selected initially: choose the casing, touchpad, and button midtone colors, then adjust the shared dot spacing, size, and screen rotation. Each ink uses its own rotated grid, and their overlaps form green, orange, violet, and darker tones. Dots become smaller in bright areas, revealing more white paper, and larger in shaded areas, merging into denser ink. There is no solid colored fill underneath them. Moving the directional light changes this dot growth across the object; real cast shadows deepen it, with exact black in the darkest shadows. Dot size scales this lighting-driven radius rather than replacing it with a fixed radius.

Choose **Halftone** for one dot-ink color over a colored base, **Ink** for two-to-six-step shading, or **Line drawing** for unshaded faces. Reset drawing restores the teal/magenta/yellow CMYK palette, 8 px spacing, 100% dot size, 0° screen rotation, and 18% shadow coverage.

Silhouette weight sets the bold outside contour independently of the thinner detail weight; detail level controls how many subtle creases appear. Internal detail lines can also be hidden in every style. Save drawing downloads a PNG of the current canvas at its display resolution, including a pixel ratio of up to 2.

Use **Around object** (−180° to 180°) and **Elevation** (−85° to 85°) to change the light direction and move the printed or stepped shadows. The light stays fixed relative to the object as you rotate the camera. Loading another model preserves your chosen direction; Reset drawing restores −21° around the object and 35° elevation. Line drawing disables these controls while retaining their values.

Load a static GLB, STL, or OBJ file up to 50 MB. Files are parsed locally in the browser. GLB resources must be embedded; materials are replaced, and no MTL is needed. CMYK preserves each imported mesh's primary material color; textures and additional material slots are not reproduced. The controller's three palette controls apply to its named parts. Draco, KTX2, external resources, animated meshes, and matching detail lines on skinned poses are outside this prototype's scope. Large or highly tessellated meshes can make edge extraction slow. Use simplified static surface meshes for the cleanest illustrations.

## Apply the treatment to a different Three.js object

```js
import { TechnicalIllustration } from './src/illustration.js';

const drawing = new TechnicalIllustration(document.querySelector('#viewport'));
drawing.setObject(myThreeObject);
drawing.setLightDirection({ azimuth: -21, elevation: 35 }); // angles in degrees
drawing.setAppearance({
  mode: 'cmyk',        // or 'halftone', 'illustration' for stepped ink, or 'line'
  weight: 3.5,         // silhouette width in display pixels
  detailWeight: 0.9,   // detail width in display pixels
  detailAngle: 28,     // crease threshold in degrees; lower reveals more detail
  steps: 3,           // discrete shadow levels in illustration mode
  shading: 0.18,      // shadow coverage
  details: true,
  dotSpacing: 8,      // spacing in display pixels
  dotSize: 1,         // dot size multiplier; 1 = 100%
  dotAngle: 0,        // rotation added to each CMYK ink screen, in degrees
  baseColor: '#f6b744',
  inkColor: '#000000',
  cmykBaseColor: '#19bad0',
  cmykAccentColor: '#f25190',
  cmykButtonColor: '#f6c832',
});
```

`setObject` takes ownership of the supplied object and its resources. It recenters and scales the model in a parent group, replaces its materials, and disposes the previous model. Give it a dedicated copy when the object or geometry is also used elsewhere. Call `dispose()` when removing the viewer.

The renderer combines an [OrthographicCamera](https://threejs.org/docs/pages/OrthographicCamera.html), lighting-driven CMYK or single-ink dots or paper-colored cel shading, pixel-sized silhouettes, and [EdgesGeometry](https://threejs.org/docs/pages/EdgesGeometry.html) for sharp creases. CMYK evaluates directional light and cast-shadow visibility independently of the selected color. It treats the palette as midtone ink colors, makes lit targets lighter toward white paper and shaded targets darker, then separates those targets into four ink coverages. Coverage determines each circular dot's radius before the four screened transmissions combine on white paper. Dots use rotated screen-space grids and retain their display-pixel spacing when the model is zoomed. [LineSegments2](https://threejs.org/docs/pages/LineSegments2.html) supplies adjustable internal stroke widths. Depth testing hides rear edges. The default 28-degree crease threshold suppresses the triangle grid on smooth surfaces; changing detail level rebuilds those edges. The outside silhouette always stays bolder than internal details. Ink mode uses discrete neutral levels and a pure-black darkest step. This is an illustration renderer rather than a CAD hidden-line export.

```sh
npm test
npm run build
```

Node tests verify the controller's closed casing and visible controls, sample geometry, centering with nested transforms, OBJ/STL/GLB parsing, invalid-file handling, ink palette boundaries, single-ink dot growth, CMYK color reconstruction and screened coverage, palette updates, style switching and disposal, custom element settings and lifecycle, and silhouette pass state and pixel sizes. Browser rendering needs visual verification on a Mac; `/home/ahmad/AGENTS.md` prohibits running browser binaries on this VPS.

`component.json` registers this release with the Components catalogue. Build this folder first, then follow `../components-site/README.md` to build, prepare and publish the catalogue. Existing 1.0.0 and 1.1.0 assets stay fixed; their embeds retain their original rendering. Bump the version before publishing changes to a released bundle.

The download includes the source, tests, bundled component, standalone demo and `THIRD_PARTY_NOTICES.md`. Three.js is distributed under the MIT license; its notice is included in the browser bundle and download.
