softbox 4.19.0 → 4.20.0

package/README.md

@@ -32,6 +32,7 @@ Balanced studio lighting, a baked soft contact shadow that grounds the model, au
 ## What you get
 
 - **[Visual presets](#visual-presets)** — `studio · product · neutral · dark · outdoor`, one word, switched live
+- **[Scenes](#scenes)** — `studio_dome · studio_soft`, one word picks the set the model stands in
 - **[Turntable](#turntable)** — one-word showcase auto-rotate that pauses while the user drags
 - **[Animations](#animations)** — GLTF clips autoplay with one word; play/pause/clip-picker API
 - **[Photoreal mode](#photoreal-mode--stills)** — progressive path tracing + `captureStill()` PNG export
@@ -84,6 +85,26 @@ Let your users switch presets with the built-in picker (off by default):
 <SimpleViewer object={url} options={{ ui: { presets: true } }} />
 ```
 
+## Scenes
+
+Presets grade the picture; **scenes** choose the set. `options.scene` selects
+the physical set the model stands in — the floor, the backdrop and how the
+built-in studio environment is built. Unlike presets, a scene is structural:
+switching one rebuilds the viewer.
+
+```tsx
+<SimpleViewer object={url} options={{ scene: 'studio_soft' }} />
+// studio_dome (default) | studio_soft
+```
+
+- `studio_dome` — the default set: shadow-catcher floor, baked soft contact
+  shadow and a crisp, contrast-pushed studio light with distinct highlights.
+- `studio_soft` — the same set lit softly: an even, low-contrast wraparound
+  light that flatters matte materials and softens speculars.
+
+Scenes compose with presets — `scene` picks the set, `preset` grades it, and
+any explicit option you pass overrides both.
+
 ## Turntable
 
 One word puts the model on a slowly rotating showcase turntable. It pauses while the user drags and resumes on release; toggling is live, like presets.

package/dist/index.d.cts

@@ -132,6 +132,12 @@ export declare enum ControlType {
     OrbitControls = "OrbitControls"
 }
 
+/** The scene every viewer stands in when none is set. */
+export declare const DEFAULT_SCENE: ViewerScene;
+
+/** The grade the studio environment is built with when none is set. */
+export declare const DEFAULT_STUDIO_LOOK: StudioLook;
+
 /**
  * Default options using the new format structure
  */
@@ -203,6 +209,8 @@ export declare interface EnvironmentOptions {
      * Runtime-tunable via `updateOptions` — presets drive this live.
      */
     environmentIntensity?: number;
+    /** Grade of the built-in studio environment; ignored when `url` is set. */
+    studioLook?: StudioLook;
 }
 
 export declare enum ErrorCode {
@@ -482,6 +490,9 @@ export declare interface RenderingOptions {
 /** The partial options for a preset, or an empty object when none is set. */
 export declare function resolvePreset(preset?: ViewerPreset): Partial<SimpleViewerOptions>;
 
+/** The partial options for a scene, or an empty object when none is set. */
+export declare function resolveScene(scene?: ViewerScene): Partial<SimpleViewerOptions>;
+
 /**
  * Click-picking and hotspot-occlusion raycast options.
  */
@@ -566,6 +577,13 @@ export declare interface SimpleViewerOptions {
      * pass overrides the preset's values.
      */
     preset?: ViewerPreset;
+    /**
+     * A one-word scene (`studio_dome`, `studio_soft`) that selects the physical
+     * set — floor, backdrop and how the studio environment is built. The
+     * structural counterpart of `preset`: switching a scene rebuilds the viewer.
+     * Any other option you pass overrides the scene's values.
+     */
+    scene?: ViewerScene;
     /**
      * Length unit the model geometry is authored in (default `'meters'`).
      * Non-meter models are rescaled on load — without touching the model's own
@@ -706,6 +724,16 @@ export declare interface SimpleViewerProps {
     children?: React_2.ReactNode;
 }
 
+/**
+ * How the built-in procedural studio environment is graded when it is built.
+ * `crisp` (the default) darkens the surround and boosts the soft-box panels so
+ * glossy materials show distinct highlights; `soft` uses the studio room
+ * as-built for an even, low-contrast wraparound light. Structural — the
+ * environment is baked once at construction, so changing it rebuilds the
+ * viewer. Scenes (`SimpleViewerOptions.scene`) drive this.
+ */
+export declare type StudioLook = 'crisp' | 'soft';
+
 export declare class ThreeViewerError extends Error {
     readonly code: ErrorCode;
     readonly context?: ErrorContext | undefined;
@@ -769,6 +797,16 @@ declare interface Vec3Like {
  */
 export declare const VIEWER_PRESETS: Record<ViewerPreset, Partial<SimpleViewerOptions>>;
 
+/**
+ * Scenes: named SETS layered over the defaults (deep-merged), the structural
+ * counterpart of `VIEWER_PRESETS`. Where a preset grades the picture (runtime
+ * look fields, applied live), a scene selects the physical set the model
+ * stands in — floor, backdrop and how the studio environment is built — so
+ * each scene only sets **structural** fields and switching one rebuilds the
+ * viewer. Explicit user options always win.
+ */
+export declare const VIEWER_SCENES: Record<ViewerScene, Partial<SimpleViewerOptions>>;
+
 /**
  * The public, Three.js-typed view of the viewer event contract — the shape
  * consumers see on the viewer handle's `events` emitter. Shares its single
@@ -855,4 +893,21 @@ declare interface ViewerEventMap_2<TObject, TCamera, TControls, THandle> {
  */
 export declare type ViewerPreset = 'studio' | 'product' | 'neutral' | 'dark' | 'outdoor';
 
+/**
+ * A one-word scene that selects the physical SET the model stands in — the
+ * floor, the backdrop geometry and how the built-in studio environment is
+ * built. Set it on `SimpleViewerOptions.scene`. The scene is the structural
+ * counterpart of the tonal `preset` axis: presets grade the picture live,
+ * scenes swap the set (switching one rebuilds the viewer). Any explicit
+ * option you pass overrides the scene's values.
+ *
+ * - `studio_dome` — the default set: invisible shadow-catcher floor, baked
+ *   soft contact shadow, crisp contrast-pushed studio environment (distinct
+ *   highlights on glossy materials) and the path-traced infinity dome.
+ * - `studio_soft` — the same set lit softly: the studio environment is used
+ *   as-built, without the contrast push, for an even, low-drama wraparound
+ *   light that flatters matte materials and softens speculars.
+ */
+export declare type ViewerScene = 'studio_dome' | 'studio_soft';
+
 export { }

package/dist/index.d.ts

@@ -132,6 +132,12 @@ export declare enum ControlType {
     OrbitControls = "OrbitControls"
 }
 
+/** The scene every viewer stands in when none is set. */
+export declare const DEFAULT_SCENE: ViewerScene;
+
+/** The grade the studio environment is built with when none is set. */
+export declare const DEFAULT_STUDIO_LOOK: StudioLook;
+
 /**
  * Default options using the new format structure
  */
@@ -203,6 +209,8 @@ export declare interface EnvironmentOptions {
      * Runtime-tunable via `updateOptions` — presets drive this live.
      */
     environmentIntensity?: number;
+    /** Grade of the built-in studio environment; ignored when `url` is set. */
+    studioLook?: StudioLook;
 }
 
 export declare enum ErrorCode {
@@ -482,6 +490,9 @@ export declare interface RenderingOptions {
 /** The partial options for a preset, or an empty object when none is set. */
 export declare function resolvePreset(preset?: ViewerPreset): Partial<SimpleViewerOptions>;
 
+/** The partial options for a scene, or an empty object when none is set. */
+export declare function resolveScene(scene?: ViewerScene): Partial<SimpleViewerOptions>;
+
 /**
  * Click-picking and hotspot-occlusion raycast options.
  */
@@ -566,6 +577,13 @@ export declare interface SimpleViewerOptions {
      * pass overrides the preset's values.
      */
     preset?: ViewerPreset;
+    /**
+     * A one-word scene (`studio_dome`, `studio_soft`) that selects the physical
+     * set — floor, backdrop and how the studio environment is built. The
+     * structural counterpart of `preset`: switching a scene rebuilds the viewer.
+     * Any other option you pass overrides the scene's values.
+     */
+    scene?: ViewerScene;
     /**
      * Length unit the model geometry is authored in (default `'meters'`).
      * Non-meter models are rescaled on load — without touching the model's own
@@ -706,6 +724,16 @@ export declare interface SimpleViewerProps {
     children?: React_2.ReactNode;
 }
 
+/**
+ * How the built-in procedural studio environment is graded when it is built.
+ * `crisp` (the default) darkens the surround and boosts the soft-box panels so
+ * glossy materials show distinct highlights; `soft` uses the studio room
+ * as-built for an even, low-contrast wraparound light. Structural — the
+ * environment is baked once at construction, so changing it rebuilds the
+ * viewer. Scenes (`SimpleViewerOptions.scene`) drive this.
+ */
+export declare type StudioLook = 'crisp' | 'soft';
+
 export declare class ThreeViewerError extends Error {
     readonly code: ErrorCode;
     readonly context?: ErrorContext | undefined;
@@ -769,6 +797,16 @@ declare interface Vec3Like {
  */
 export declare const VIEWER_PRESETS: Record<ViewerPreset, Partial<SimpleViewerOptions>>;
 
+/**
+ * Scenes: named SETS layered over the defaults (deep-merged), the structural
+ * counterpart of `VIEWER_PRESETS`. Where a preset grades the picture (runtime
+ * look fields, applied live), a scene selects the physical set the model
+ * stands in — floor, backdrop and how the studio environment is built — so
+ * each scene only sets **structural** fields and switching one rebuilds the
+ * viewer. Explicit user options always win.
+ */
+export declare const VIEWER_SCENES: Record<ViewerScene, Partial<SimpleViewerOptions>>;
+
 /**
  * The public, Three.js-typed view of the viewer event contract — the shape
  * consumers see on the viewer handle's `events` emitter. Shares its single
@@ -855,4 +893,21 @@ declare interface ViewerEventMap_2<TObject, TCamera, TControls, THandle> {
  */
 export declare type ViewerPreset = 'studio' | 'product' | 'neutral' | 'dark' | 'outdoor';
 
+/**
+ * A one-word scene that selects the physical SET the model stands in — the
+ * floor, the backdrop geometry and how the built-in studio environment is
+ * built. Set it on `SimpleViewerOptions.scene`. The scene is the structural
+ * counterpart of the tonal `preset` axis: presets grade the picture live,
+ * scenes swap the set (switching one rebuilds the viewer). Any explicit
+ * option you pass overrides the scene's values.
+ *
+ * - `studio_dome` — the default set: invisible shadow-catcher floor, baked
+ *   soft contact shadow, crisp contrast-pushed studio environment (distinct
+ *   highlights on glossy materials) and the path-traced infinity dome.
+ * - `studio_soft` — the same set lit softly: the studio environment is used
+ *   as-built, without the contrast push, for an even, low-drama wraparound
+ *   light that flatters matte materials and softens speculars.
+ */
+export declare type ViewerScene = 'studio_dome' | 'studio_soft';
+
 export { }