softbox 4.21.0 → 4.23.0

package/dist/index.d.cts

@@ -132,6 +132,29 @@ export declare enum ControlType {
     OrbitControls = "OrbitControls"
 }
 
+/**
+ * Photographic PBR maps for the outdoor concrete ground (CC0, Poly Haven;
+ * ~600 KB total, same CDN and override/self-host contract as the HDRI).
+ * Captured micro-structure is what reads as real concrete; the procedural
+ * generator stays as the offline fallback when these fail to fetch.
+ */
+export declare const DEFAULT_OUTDOOR_CONCRETE_TEXTURES: {
+    readonly texture: "https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/concrete_floor_02/concrete_floor_02_diff_1k.jpg";
+    readonly normalMap: "https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/concrete_floor_02/concrete_floor_02_nor_gl_1k.jpg";
+    readonly roughnessMap: "https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/concrete_floor_02/concrete_floor_02_rough_1k.jpg";
+};
+
+/**
+ * The daylight HDRI `outdoor_concrete` lights with when no explicit
+ * `environment.url` is given: a bright partly-cloudy sky (CC0, Poly Haven;
+ * the projection shows its soft open terrain at the horizon), fetched on
+ * demand from their CDN — the one network request the outdoor scene makes.
+ * Pass your own `environment.url` to override or self-host, exactly like
+ * the DRACO/KTX2 decoder paths. (Urban candidates — potsdamer_platz,
+ * quarry_01 — were rejected visually: dusk-dark and olive-tinted grounds.)
+ */
+export declare const DEFAULT_OUTDOOR_HDRI_URL = "https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/2k/kloofendal_48d_partly_cloudy_puresky_2k.hdr";
+
 /** The scene every viewer stands in when none is set. */
 export declare const DEFAULT_SCENE: ViewerScene;
 
@@ -211,6 +234,23 @@ export declare interface EnvironmentOptions {
     environmentIntensity?: number;
     /** Grade of the built-in studio environment; ignored when `url` is set. */
     studioLook?: StudioLook;
+    /**
+     * Project the environment map onto a virtual ground plane so the model
+     * appears to STAND in the environment instead of floating in front of it —
+     * the outdoor scenes' horizon treatment (three's GroundedSkybox). `true`
+     * uses the defaults (height 2m — a typical eye-level HDRI shot — and a
+     * 120m world radius); pass numbers to match an HDRI shot from another
+     * height or a larger set. Only applies when `url` is set. Structural —
+     * changing it rebuilds the viewer.
+     *
+     * While active the projection mesh IS the visible backdrop, so
+     * `backgroundBlurriness` has no effect (`backgroundIntensity` is emulated
+     * by dimming the projection).
+     */
+    groundProjection?: boolean | {
+        height?: number;
+        radius?: number;
+    };
 }
 
 export declare enum ErrorCode {
@@ -251,7 +291,7 @@ export declare interface GridHelperOptions {
     divisions?: number;
     colorCenterLine?: string | number;
     colorGrid?: string | number;
-    type?: 'shadow_floor' | 'square_wire' | 'hexagonal_wire' | 'hexagonal_glass' | 'stone_tiles';
+    type?: 'shadow_floor' | 'concrete_disc' | 'square_wire' | 'hexagonal_wire' | 'hexagonal_glass' | 'stone_tiles';
     opacity?: number;
     styleOptions?: {
         hexRadius?: number;
@@ -541,6 +581,14 @@ export declare interface SimpleViewerHandle {
     captureVideo: (options?: CaptureVideoOptions) => Promise<Blob>;
     /** Clip names of the loaded model, in file order (empty when none). */
     getAnimationNames: () => string[];
+    /** KHR_materials_variants names of the loaded model (empty when none). */
+    getVariantNames: () => string[];
+    /**
+     * Switch the loaded model to a material variant; `null` restores the
+     * authored materials. Applies live (no reload). Throws `INVALID_PARAMETER`
+     * on a variant name the model does not carry.
+     */
+    setVariant: (variant: string | null) => void;
     /**
      * Plays one clip by name, or ALL clips when no name is given (looped).
      * Throws `INVALID_PARAMETER` on a clip name the model does not carry.
@@ -584,6 +632,16 @@ export declare interface SimpleViewerOptions {
      * Any other option you pass overrides the scene's values.
      */
     scene?: ViewerScene;
+    /**
+     * KHR_materials_variants variant to show (e.g. a product colorway baked
+     * into the GLB). Applies LIVE — switching never rebuilds the viewer or
+     * reloads the model. `null` shows the authored default materials; leaving
+     * the option out is "uncontrolled" (an imperative `handle.setVariant()`
+     * pick survives other option changes); an unknown name warns and keeps
+     * the defaults. Enumerate the model's variants via
+     * `handle.getVariantNames()`.
+     */
+    variant?: string | null;
     /**
      * Length unit the model geometry is authored in (default `'meters'`).
      * Non-meter models are rescaled on load — without touching the model's own
@@ -797,14 +855,6 @@ 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>>;
 
 /**
@@ -905,9 +955,14 @@ export declare type ViewerPreset = 'studio' | 'product' | 'neutral' | 'dark' | '
  *   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.
+ *   as-built, without the contrast push, plus a rebalanced rig (the key steps
+ *   back, the rim edge nearly goes, the fill opens the shadows) for an even,
+ *   low-drama read that flatters matte materials.
+ * - `outdoor_concrete` — open air: a real daylight HDRI lights the model and
+ *   paints the sky, standing on a large matte concrete ground disc. The HDRI
+ *   is fetched from a CDN by default (the one network request this scene
+ *   makes); pass your own `environment.url` to override or self-host it.
  */
-export declare type ViewerScene = 'studio_dome' | 'studio_soft';
+export declare type ViewerScene = 'studio_dome' | 'studio_soft' | 'outdoor_concrete';
 
 export { }

package/dist/index.d.ts

@@ -132,6 +132,29 @@ export declare enum ControlType {
     OrbitControls = "OrbitControls"
 }
 
+/**
+ * Photographic PBR maps for the outdoor concrete ground (CC0, Poly Haven;
+ * ~600 KB total, same CDN and override/self-host contract as the HDRI).
+ * Captured micro-structure is what reads as real concrete; the procedural
+ * generator stays as the offline fallback when these fail to fetch.
+ */
+export declare const DEFAULT_OUTDOOR_CONCRETE_TEXTURES: {
+    readonly texture: "https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/concrete_floor_02/concrete_floor_02_diff_1k.jpg";
+    readonly normalMap: "https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/concrete_floor_02/concrete_floor_02_nor_gl_1k.jpg";
+    readonly roughnessMap: "https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/concrete_floor_02/concrete_floor_02_rough_1k.jpg";
+};
+
+/**
+ * The daylight HDRI `outdoor_concrete` lights with when no explicit
+ * `environment.url` is given: a bright partly-cloudy sky (CC0, Poly Haven;
+ * the projection shows its soft open terrain at the horizon), fetched on
+ * demand from their CDN — the one network request the outdoor scene makes.
+ * Pass your own `environment.url` to override or self-host, exactly like
+ * the DRACO/KTX2 decoder paths. (Urban candidates — potsdamer_platz,
+ * quarry_01 — were rejected visually: dusk-dark and olive-tinted grounds.)
+ */
+export declare const DEFAULT_OUTDOOR_HDRI_URL = "https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/2k/kloofendal_48d_partly_cloudy_puresky_2k.hdr";
+
 /** The scene every viewer stands in when none is set. */
 export declare const DEFAULT_SCENE: ViewerScene;
 
@@ -211,6 +234,23 @@ export declare interface EnvironmentOptions {
     environmentIntensity?: number;
     /** Grade of the built-in studio environment; ignored when `url` is set. */
     studioLook?: StudioLook;
+    /**
+     * Project the environment map onto a virtual ground plane so the model
+     * appears to STAND in the environment instead of floating in front of it —
+     * the outdoor scenes' horizon treatment (three's GroundedSkybox). `true`
+     * uses the defaults (height 2m — a typical eye-level HDRI shot — and a
+     * 120m world radius); pass numbers to match an HDRI shot from another
+     * height or a larger set. Only applies when `url` is set. Structural —
+     * changing it rebuilds the viewer.
+     *
+     * While active the projection mesh IS the visible backdrop, so
+     * `backgroundBlurriness` has no effect (`backgroundIntensity` is emulated
+     * by dimming the projection).
+     */
+    groundProjection?: boolean | {
+        height?: number;
+        radius?: number;
+    };
 }
 
 export declare enum ErrorCode {
@@ -251,7 +291,7 @@ export declare interface GridHelperOptions {
     divisions?: number;
     colorCenterLine?: string | number;
     colorGrid?: string | number;
-    type?: 'shadow_floor' | 'square_wire' | 'hexagonal_wire' | 'hexagonal_glass' | 'stone_tiles';
+    type?: 'shadow_floor' | 'concrete_disc' | 'square_wire' | 'hexagonal_wire' | 'hexagonal_glass' | 'stone_tiles';
     opacity?: number;
     styleOptions?: {
         hexRadius?: number;
@@ -541,6 +581,14 @@ export declare interface SimpleViewerHandle {
     captureVideo: (options?: CaptureVideoOptions) => Promise<Blob>;
     /** Clip names of the loaded model, in file order (empty when none). */
     getAnimationNames: () => string[];
+    /** KHR_materials_variants names of the loaded model (empty when none). */
+    getVariantNames: () => string[];
+    /**
+     * Switch the loaded model to a material variant; `null` restores the
+     * authored materials. Applies live (no reload). Throws `INVALID_PARAMETER`
+     * on a variant name the model does not carry.
+     */
+    setVariant: (variant: string | null) => void;
     /**
      * Plays one clip by name, or ALL clips when no name is given (looped).
      * Throws `INVALID_PARAMETER` on a clip name the model does not carry.
@@ -584,6 +632,16 @@ export declare interface SimpleViewerOptions {
      * Any other option you pass overrides the scene's values.
      */
     scene?: ViewerScene;
+    /**
+     * KHR_materials_variants variant to show (e.g. a product colorway baked
+     * into the GLB). Applies LIVE — switching never rebuilds the viewer or
+     * reloads the model. `null` shows the authored default materials; leaving
+     * the option out is "uncontrolled" (an imperative `handle.setVariant()`
+     * pick survives other option changes); an unknown name warns and keeps
+     * the defaults. Enumerate the model's variants via
+     * `handle.getVariantNames()`.
+     */
+    variant?: string | null;
     /**
      * Length unit the model geometry is authored in (default `'meters'`).
      * Non-meter models are rescaled on load — without touching the model's own
@@ -797,14 +855,6 @@ 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>>;
 
 /**
@@ -905,9 +955,14 @@ export declare type ViewerPreset = 'studio' | 'product' | 'neutral' | 'dark' | '
  *   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.
+ *   as-built, without the contrast push, plus a rebalanced rig (the key steps
+ *   back, the rim edge nearly goes, the fill opens the shadows) for an even,
+ *   low-drama read that flatters matte materials.
+ * - `outdoor_concrete` — open air: a real daylight HDRI lights the model and
+ *   paints the sky, standing on a large matte concrete ground disc. The HDRI
+ *   is fetched from a CDN by default (the one network request this scene
+ *   makes); pass your own `environment.url` to override or self-host it.
  */
-export declare type ViewerScene = 'studio_dome' | 'studio_soft';
+export declare type ViewerScene = 'studio_dome' | 'studio_soft' | 'outdoor_concrete';
 
 export { }