@3driseai/3drise-viewer 0.1.7 → 0.1.8

package/dist/presets/landscapePresets.js

@@ -0,0 +1,194 @@
+import { defaultLandscapeSurface } from '../types/landscapeConfigs.js';
+const surface = (patch) => ({
+    ...defaultLandscapeSurface,
+    ...patch,
+});
+const grass = surface({
+    name: 'Grass',
+    diffuse: 'grass_col.jpg',
+    normal: 'grass_norm.jpg',
+    displacement: 'grass_dsp.png',
+    repeat: 260,
+    normalStrength: 0.45,
+    saturation: 0.85,
+    tint: '#b6c4a8',
+    roughness: 0.95,
+    heightBlend: 0.5,
+    aperiodic: true,
+});
+const mud = surface({
+    name: 'Mud',
+    diffuse: 'mud_col.jpg',
+    normal: 'mud_norm.jpg',
+    displacement: 'mud_dsp.png',
+    repeat: 300,
+    normalStrength: 0.6,
+    saturation: 0.8,
+    roughness: 0.88,
+    heightBlend: 0.7,
+    aperiodic: true,
+});
+const cliff = surface({
+    name: 'Cliff',
+    diffuse: 'cliff_col.jpg',
+    normal: 'cliff_norm.jpg',
+    displacement: 'cliff_dsp.png',
+    repeat: 220,
+    normalStrength: 0.75,
+    saturation: 0.7,
+    tint: '#cfc9c2',
+    roughness: 0.82,
+    heightBlend: 0.85,
+    // The one surface that needs world-axis projection: on a vertical face the
+    // tile's own UV is stretched to a smear.
+    triplanar: true,
+    aperiodic: true,
+});
+const rock = surface({
+    name: 'Rock',
+    diffuse: 'rock_col.jpg',
+    normal: 'rock_norm.jpg',
+    displacement: 'rock_dsp.png',
+    repeat: 240,
+    normalStrength: 0.7,
+    saturation: 0.65,
+    tint: '#c8c4bd',
+    roughness: 0.86,
+    heightBlend: 0.85,
+    triplanar: true,
+    aperiodic: true,
+});
+export const landscapePresets = [
+    {
+        name: 'Highlands',
+        description: 'The authored case: two splat maps place grass, mud, cliff and rock, '
+            + 'with height blending at every transition and world-axis projection on the two rock layers.',
+        tags: ['grass', 'rock', 'valley', 'authored'],
+        assets: {
+            heightMap: 'heightmap.png',
+            splatMaps: ['splat0.png', 'splat1.png'],
+            aoMap: 'ao.png',
+        },
+        surfaces: [rock, cliff, mud, grass],
+        settings: {
+            heightEncoding: 'grayscale',
+            splatSource: 'maps',
+            size: 2048,
+            elevationScale: 340,
+            elevationBias: 0,
+            smoothness: 1.5,
+            surfaceSamples: 3,
+            macroVariation: 0.22,
+            macroSize: 700,
+        },
+    },
+    {
+        name: 'Highlands (generated splat)',
+        description: 'The same heightmap with no splat maps at all — surfaces placed by height and slope, '
+            + 'rock last. This is what a bare heightmap looks like on drop, which the reference '
+            + 'implementation cannot render at all.',
+        tags: ['auto', 'generated', 'slope'],
+        assets: {
+            heightMap: 'heightmap.png',
+            aoMap: 'ao.png',
+        },
+        surfaces: [grass, mud, cliff],
+        settings: {
+            heightEncoding: 'grayscale',
+            splatSource: 'auto',
+            size: 2048,
+            elevationScale: 340,
+            smoothness: 1.5,
+            surfaceSamples: 3,
+            macroVariation: 0.28,
+            macroSize: 800,
+            autoSplat: {
+                bands: [0.15, 0.55, 0.9],
+                bandWidth: 0.5,
+                slopeStart: 0.3,
+                slopeEnd: 0.6,
+                noise: 0.14,
+                noiseSize: 350,
+            },
+        },
+    },
+];
+/**
+ * Fill a preset's file names in from wherever the caller keeps its assets.
+ *
+ * Surfaces whose diffuse cannot be resolved are dropped rather than rendered as
+ * a hole — a surface with no albedo is skipped by the renderer anyway, and an
+ * empty slot in the middle of the list would silently shift every splat channel
+ * after it. A missing normal or height map is not fatal: those degrade to a flat
+ * normal and a linear blend, which is what the reference implementation does for
+ * every surface always.
+ *
+ * The heightmap is the one thing that cannot be missing — without it there is no
+ * landscape — so an unresolved heightmap returns a config with `enabled: false`
+ * and the name in `missing`, for the panel to say so.
+ */
+export function resolveLandscapePreset(preset, resolve) {
+    const missing = [];
+    const take = (name) => {
+        if (!name)
+            return '';
+        const url = resolve(name);
+        if (!url) {
+            missing.push(name);
+            return '';
+        }
+        return url;
+    };
+    const heightMap = take(preset.assets.heightMap);
+    const splatMaps = (preset.assets.splatMaps ?? []).map(take).filter(Boolean);
+    const aoMap = take(preset.assets.aoMap);
+    const surfaces = preset.surfaces
+        .map((s) => ({
+        ...s,
+        diffuse: take(s.diffuse),
+        normal: take(s.normal),
+        displacement: take(s.displacement),
+    }))
+        .filter((s) => !!s.diffuse);
+    return {
+        config: {
+            ...preset.settings,
+            enabled: !!heightMap && surfaces.length > 0,
+            heightMap,
+            splatMaps,
+            aoMap,
+            surfaces,
+            // A preset that lost its splat maps still has to render, so it falls
+            // back to the generated splat rather than to a blank ground.
+            splatSource: splatMaps.length > 0 ? (preset.settings.splatSource ?? 'maps') : 'auto',
+            preset: preset.name,
+        },
+        missing,
+    };
+}
+export function getLandscapePresetByName(name) {
+    return landscapePresets.find((preset) => preset.name === name);
+}
+/** Every file name the built-in presets need, for a client that wants to check
+ *  what is uploaded before offering them. */
+export function landscapePresetAssetNames() {
+    const names = new Set();
+    for (const preset of landscapePresets) {
+        names.add(preset.assets.heightMap);
+        preset.assets.splatMaps?.forEach((n) => names.add(n));
+        if (preset.assets.aoMap)
+            names.add(preset.assets.aoMap);
+        for (const s of preset.surfaces) {
+            names.add(s.diffuse);
+            if (s.normal)
+                names.add(s.normal);
+            if (s.displacement)
+                names.add(s.displacement);
+        }
+    }
+    return [...names];
+}
+export function searchLandscapePresetsByTags(tags) {
+    const wanted = tags.map((t) => t.toLowerCase());
+    return landscapePresets.filter((preset) => preset.tags.some((tag) => wanted.includes(tag.toLowerCase())));
+}

package/dist/presets/landscapeTypes.d.ts

@@ -0,0 +1,195 @@
+import type { LandscapeConfig, LandscapeQualityConfig, LandscapeSurface } from '../types/landscapeConfigs';
+/**
+ * Landscape types and shapes — the two things a person actually picks.
+ *
+ * ## The split
+ *
+ * A landscape is two independent choices:
+ *
+ *   SHAPE  the heightmap. Mountains, rolling hills, dunes, a valley.
+ *   TYPE   the biome. Grassland, rocky, snow, sand.
+ *
+ * They are orthogonal — any shape can wear any type — so eight of each is
+ * sixty-four landscapes from sixteen folders. That is the whole reason the panel
+ * can be two pictures instead of thirty-three rows.
+ *
+ * ## Why a type is code and a pack is a folder
+ *
+ * A type is a dozen numbers: which surface packs, in what order, with what
+ * height and slope bands, tints, repeats and roughness. If a type were a folder
+ * of textures, re-tuning a band would mean re-uploading. So the files are
+ * *packs* (a tiling material) and *shapes* (a heightmap), and the recipe lives
+ * here.
+ *
+ * A type also needs no authored splat map — it uses the generated height-and-
+ * slope splat. That is what makes "pick a type" possible at all: otherwise every
+ * shape x type pairing would need its own painted splat map, which is sixty-four
+ * files that do not exist. Authored splats stay available in the Advanced tab,
+ * which is the only place they earn their keep.
+ */
+/** A pack resolved from the asset folder: file names for one tiling material. */
+export interface LandscapePackRef {
+    /** Folder name under `surfaces/`. */
+    pack: string;
+    /** Per-type overrides on top of `defaultLandscapeSurface`. */
+    surface?: Partial<LandscapeSurface>;
+    /** Height fraction this surface is centred on. The LAST entry in a type is
+     *  the rock layer and is placed by slope instead. */
+    band?: number;
+    /**
+     * How many WORLD METRES one tile of this texture covers.
+     *
+     * Not a repeat count, deliberately. `repeat` is relative to the tile, so a
+     * recipe written at 2 km silently doubles its texture scale when someone
+     * drags Size to 4 km, and the ground goes from grass to mush. In metres the
+     * recipe is size-independent and the number means something: a grass texture
+     * is about two and a half metres across, a rock face about four.
+     *
+     * The first version wrote repeat counts and got roughly 8-10 m per tile,
+     * which is what made the close-up read as giant blobs instead of ground.
+     */
+    metres?: number;
+}
+export interface LandscapeTypeDef {
+    id: string;
+    /** What the picker shows. */
+    label: string;
+    /** One line under the label. */
+    description: string;
+    /** Bottom of the height range first; the last entry is the slope/rock layer. */
+    packs: LandscapePackRef[];
+    /** Auto-splat shaping for this biome. */
+    splat: {
+        bandWidth: number;
+        slopeStart: number;
+        slopeEnd: number;
+        noise: number;
+        noiseSize: number;
+    };
+    /** Config nudges that make this biome read right — macro break-up mostly. */
+    settings?: Partial<LandscapeConfig>;
+    /** Which pack's thumbnail represents the type in the picker, and the pack
+     *  without which the type is not itself — Snow without `snow_fresh` is just
+     *  rock. Defaults to the first pack, which is the one covering most of the
+     *  ground. Used by `landscapeTypeAvailability`. */
+    thumbPack?: string;
+}
+/** Texture repeats across the tile, from a real-world tile size. Clamped: below
+ *  about half a metre a ground texture aliases before it reads as detail, and
+ *  above about forty it is wallpaper. */
+export declare function repeatForMetres(size: number, metres: number): number;
+export declare const landscapeTypes: LandscapeTypeDef[];
+export declare function getLandscapeType(id: string): LandscapeTypeDef | undefined;
+/** Every surface pack any type refers to — for a client that wants to know what
+ *  to upload, or which types it can offer. */
+export declare function landscapeTypePacks(type: LandscapeTypeDef): string[];
+/** One type, what it is missing, and whether that is fatal. */
+export interface LandscapeTypeAvailability {
+    type: LandscapeTypeDef;
+    /** Every pack named by the recipe that is not in `havePacks`. */
+    missingPacks: string[];
+    /** The subset of `missingPacks` that actually prevents the type being
+     *  offered — the slope layer and the signature pack. */
+    blockingPacks: string[];
+    /** Missing but survivable: middle height bands. The type renders with a
+     *  wider gap between its remaining layers, which is a poorer version of
+     *  itself, not a broken one. */
+    reducedPacks: string[];
+    available: boolean;
+}
+/**
+ * Every type, with the reason each unavailable one is unavailable.
+ *
+ * The packs in a type are NOT interchangeable, so "needs all of them" is the
+ * wrong rule and this is the right one. Two of them are load-bearing:
+ *
+ *   THE LAST PACK is the slope layer. The auto-splat block in
+ *   `landscapeCore.glsl` bands every surface by height, multiplies all but the
+ *   last by `1 - rock`, and then forces the last one on by slope. Drop it and
+ *   the next pack up is silently promoted into that role — a ground texture
+ *   smeared vertically up every cliff face, which is the ugliest thing this
+ *   material can do.
+ *
+ *   THE SIGNATURE PACK (`thumbPack`, else the first) is what makes the type
+ *   that type. Snow without `snow_fresh` is rock, and offering it under the
+ *   name Snow is worse than not offering it.
+ *
+ * Everything in between is a middle height band. Losing one widens the gap
+ * between the layers that remain; `resolveLandscapeType` already rebuilds the
+ * band array from the surfaces that actually resolved, so nothing lands at the
+ * wrong altitude. That is a poorer version of the biome, not a broken one, and
+ * it is not worth blocking a type over — Sand with dune sand and boulders but
+ * no ripple layer is still recognisably sand.
+ */
+export declare function landscapeTypeAvailability(havePacks: Iterable<string>): LandscapeTypeAvailability[];
+export interface LandscapeShapeDef {
+    /** Folder name under `terrains/`. */
+    id: string;
+    label: string;
+    description: string;
+    /** Sensible world size and relief for this shape, in metres. The Basic tab's
+     *  two sliders start here rather than at a global default, because a dune
+     *  field and an alpine range are not the same scene at the same numbers. */
+    size: number;
+    elevation: number;
+    /** Authored splat maps exist for this shape and are worth preferring over the
+     *  generated one. Only `highlands` has them today. */
+    hasSplatMaps?: boolean;
+}
+export declare const landscapeShapes: LandscapeShapeDef[];
+export declare function getLandscapeShape(id: string): LandscapeShapeDef | undefined;
+export type LandscapeDetail = 'draft' | 'balanced' | 'high';
+/**
+ * The six knobs a non-expert cannot reason about individually but has a clear
+ * opinion about collectively. `meshError` is in world units and therefore scales
+ * with the landscape's relief, so it is applied as a FRACTION of elevation
+ * rather than as a constant — 1.5 m of error on a 90 m dune field is invisible,
+ * on a 900 m range it is a stepped silhouette.
+ */
+export declare const LANDSCAPE_DETAIL: Record<LandscapeDetail, {
+    label: string;
+    description: string;
+    /** meshError is in world units, so it scales with relief rather than being a
+     *  constant: 1.5 m of error is invisible on a 90 m dune field and a stepped
+     *  silhouette on a 900 m range. */
+    meshErrorFraction: number;
+    /** Lives in the CONFIG, not in quality — it is what the material blends, not
+     *  what the mesh costs. Carried here so one dial still sets it. */
+    surfaceSamples: number;
+    quality: Partial<LandscapeQualityConfig>;
+}>;
+export declare function landscapeQualityForDetail(detail: LandscapeDetail, elevation: number): LandscapeQualityConfig;
+/** Best guess at which detail level a config came from, so the Basic tab can
+ *  show the right button after an Advanced edit — or show none, which is the
+ *  honest answer once someone has hand-tuned it. */
+export declare function detectLandscapeDetail(quality: LandscapeQualityConfig, surfaceSamples: number): LandscapeDetail | null;
+/** How the client hands over what it found in the asset folder. */
+export interface LandscapeAssetIndex {
+    /** `surfaces/<pack>/<role>` -> URL. Absent roles are simply missing. */
+    pack(name: string, role: 'albedo' | 'normal' | 'height' | 'thumb'): string | null;
+    /** `terrains/<shape>/<role>` -> URL. */
+    shape(name: string, role: 'height' | 'splat0' | 'splat1' | 'ao' | 'preview'): string | null;
+}
+export interface ResolvedLandscapeType {
+    config: Partial<LandscapeConfig>;
+    quality: LandscapeQualityConfig;
+    /** Packs or maps the index could not supply. Empty means it is whole. */
+    missing: string[];
+}
+/**
+ * Two picks and a detail level to a whole config.
+ *
+ * A pack with no albedo is dropped, not rendered as a hole — a surface with no
+ * albedo is skipped by the renderer anyway, and an empty slot in the middle of
+ * the list would shift the bands of every layer after it.
+ *
+ * The shape's own `size` and `elevation` are the starting point rather than a
+ * global default, because a dune field and an alpine range are not the same
+ * scene at the same numbers. The caller overrides them once the user touches a
+ * slider.
+ */
+export declare function resolveLandscapeType(typeId: string, shapeId: string, index: LandscapeAssetIndex, detail?: LandscapeDetail, override?: {
+    size?: number;
+    elevation?: number;
+}): ResolvedLandscapeType;
+//# sourceMappingURL=landscapeTypes.d.ts.map

package/dist/presets/landscapeTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"landscapeTypes.d.ts","sourceRoot":"","sources":["../../src/presets/landscapeTypes.ts"],"names":[],"mappings":"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"}