--- title: "Scene" description: "Clover's 3D view for IIIF Presentation 4 Scenes: glTF models, lit and framed, turned and zoomed by pointer, key or control, on its own or in a Root." url: https://clover.iiif.library.northwestern.edu/docs/scene version: "4" --- # Scene \ (web components: \)26 kB loaded by a page with it alone to first view, gzipped (web components: 74 kB loaded by a page with it alone to first view, styles included, gzipped) 3D, as Presentation 4 shapes it: a Scene’s glTF models, lit, framed and turned in your hands. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. **React** ```jsx
``` **Web components** ```html
``` ## API reference Draws the Presentation 4 Scene you hand it, or loads one itself (`iiifContent` (web components: `iiif-content`): a Manifest gives its first Scene). Inside a `Root` (web components: ``), given nothing, it draws the Root’s view when that is a Scene; [`Body` (web components: ``)](https://clover.iiif.library.northwestern.edu/docs/body) draws a Scene view with it, unless a renderer of yours claims it. It fills its parent, so give the parent a height. What draws the models, Clover’s own renderer (or three.js, `engine="three"`, which a page opts into), loads the first time a Scene comes near the window. A drag turns the models and a pinch zooms. The controls sit together in the lower right, over a soft shade, and show while the pointer moves over the view or keyboard focus is in it: zoom and full screen in a row, then the rotate pad. Drag the pad’s disc to turn the models as you would drag the view; the globe on it turns with them and shows where their front is. Each arrow turns them the way it points, a step for a press, or on and on while you hold it, and Reset view, in the pad’s corner, brings them home. With the view focused, the arrow keys turn the models (with Shift, further), R and Shift+R turn them right and left, plus and minus zoom, and 0 resets. A plain wheel scrolls the page. **React** | Prop | Type | Default | Description | | ---------------- | ------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `scene` | `object` | The Root’s view | A Presentation 4 Scene to draw; `toPresentation4()` upgrades older ones. | | `iiifContent` | `string \| object` | — | A Scene to load and draw, or a Manifest’s first: URL or JSON. | | `label` | language map or `string` | The Scene’s label | The view’s accessible name. | | `language` | `string` | The reader’s, or the Root’s | The language to read its label, summary and metadata in. | | `highContrast` | `boolean` | `false` | Clover’s higher-contrast mode: the accent kept to rings, outlines and marks, never under words or a glyph. Inside a `Root`, the Root’s too; on wherever the reader’s system asks for more contrast. | | `controls` | `boolean \| { zoom, fullPage, rotation, reset, information }` | `true` | All of Clover’s controls, none, or all but those set `false`. | | `controlButtons` | `object` | — | Components of your own for any control, as Canvas takes them. | | `options` | `{ request?, hideDelay? }` | — | Credentials and headers for the Scene and its models; the controls’ fade. | | `engine` | `"clover" \| "three"` | `"clover"` | Clover’s own WebGL2 renderer, or three.js, once the page registers it. | | `className` | `string` | — | Added to `clover-canvas clover-scene`, on its `figure`. | | `children` | `ReactNode` | — | Your own controls, after Clover’s. | **Web components** ### `` A IIIF Presentation 4 Scene, drawn in 3D: the glTF models it paints, lit and framed, turned and zoomed by pointer, key or control. Its 3D library loads only when one is drawn. Alone, it draws what it is given; inside a clover-root, given nothing, the root's view when that is a Scene. As tall as --clover-body-height (60vh) or its own style. | Name | Type | Default | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `iiif-content` | `string` | — | A Scene, or a Manifest (its first Scene), by URL, in any Presentation version. | | `label` | `string` | — | The view's name. A Scene names it by its own label. | | `language` | `string` | — | The language to read IIIF text in. | | `high-contrast` | `boolean` | `false` | Clover's higher-contrast mode, for what is inside: the accent kept to rings, outlines and marks, never under words or a glyph, where the controls' dark fill takes its place, edged in the accent. On wherever the reader's system asks for more contrast, too. | | `controls` | `boolean` | `true` | "false" leaves out the controls over the Body. | | `engine` | `"clover" \| "three"` | `clover` | What draws the models: Clover's own WebGL2 renderer ("clover"), or three.js ("three"), once the page loads web-components/three.mjs, for what Clover's does not draw yet (glTF's material extensions, skins and morph targets at rest, sparse accessors). | | `.iiifContent` | `string \| Record \| null` | — | As a property: What to load and draw, as a URL or a IIIF resource. | | `.scene` | `Record \| null` | — | A Presentation 4 Scene to draw. | | `.options` | `{ request?: Record; hideDelay?: number } \| null` | — | request: credentials and headers for the Scene and its models; hideDelay: how long the controls stay after a mouse stops, in milliseconds. | | `.controls` | `boolean \| { zoom?: boolean; fullPage?: boolean; rotation?: boolean; reset?: boolean; information?: boolean } \| null` | — | As a property: Which of the Body's controls it shows: false for none, or some ({ rotation: false }), in place of the attribute. | ## Examples ### In a Viewer The Viewer draws a Manifest’s Scenes with it, as it draws its Canvases with Canvas. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. **React** ```jsx ``` **Web components** ```html ``` ### Customizing engine Clover draws a Scene with its own engine, `clover`, by default, for its size. Each engine loads the first time a Scene comes near the window: - `engine="clover"`, Clover’s own WebGL2 renderer: 8 kB gzipped. - `engine="three"`, three.js: 158 kB gzipped, for what Clover’s does not draw yet. Choose three.js for what Clover’s engine does not draw yet: glTF’s material extensions beyond unlit, such as clearcoat, transmission and sheen, skins and morph targets (at rest), sparse accessors and a second set of texture coordinates. Clover’s engine says which of these a model needs, in an alert, rather than drawing it wrong. Neither engine draws compressed models (Draco, Meshopt, KTX2) or plays animations yet. three.js is opt-in: install it, and register it once, before a Scene draws. A page that never does carries none of it. **React** ```js // npm install three import { registerThreeEngine } from "@nulib/clover/three"; registerThreeEngine(); ``` **Web components** ```html ``` Both of these are a Scene with the same model, seen from the same camera; only their `engine` differs. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. > > Scene with `clover` as engine. > > Scene with `three` as engine. **React** ```jsx ``` **Web components** ```html ``` ### Scene or Body In a layout, place [`Body` (web components: ``)](https://clover.iiif.library.northwestern.edu/docs/body). It handles every container the IIIF Presentation API defines, a Canvas, a Timeline or a Scene, so as your reader moves from one view to the next, it switches between Canvas, Timeline and Scene on the fly. It adds a height, your renderers and the loading mark too. **React** ```jsx ``` **Web components** ```html ``` ## Formats Scene draws glTF 2.0, the open format for 3D on the web that the IIIF Cookbook’s Scenes paint, as binary (`.glb`, `model/gltf-binary`) or JSON (`.gltf`, `model/gltf+json`), with its materials (metal and roughness), textures and node hierarchies. A model in any other format shows an alert saying why, never a broken view. The IIIF Cookbook’s [0608, Simplest Manifest: 3D](https://iiif.io/api/cookbook/recipe/0608-mvm-3d/) draws as it asks: one model at the Scene’s origin, lit and framed by Clover, since the Scene names no camera or light. Models placed by a `PointSelector` on their target, and turned, scaled and moved by the transforms on their `SpecificResource`, in order, are drawn too. ## Accessibility The view is announced as a rotatable 3D model, named by the Scene’s label, and its description lists its keys. Everything a drag or a pinch does, a key or a button does too, so the models turn and zoom without a pointer. The controls are named buttons, each with its key in its popover and at least 24px across, in the order up, left, right, down, Reset view; on a small view they shrink, but never under 24px. The pad’s disc is a convenience for a mouse or a finger, so screen readers skip it: its arrows and the view’s keys do everything it does. The controls stay on screen while keyboard focus is in them. Nothing moves on its own, and a model that cannot be drawn is explained in an alert. ## Size A page with a Scene alone loads the figure beside the title to its first view: the Body, its controls, the reading of the Scene, and Clover’s engine, which loads as the Scene comes near the window. A Viewer’s templates load neither until a Scene shows: the Default template is 95 kB to first view. ## What’s next - A Scene’s own cameras and lights, which Presentation 4 can name. - Annotations in 3D: comments and links on a point of a model, and their list. - Scenes within Scenes, sound in a Scene, and models’ animations. - Panning, and a camera position kept in a share link.