All files / viewer/src settings.ts

93.54% Statements 58/62
84.48% Branches 49/58
100% Functions 8/8
95.23% Lines 40/42

Press n or j to go to the next uncovered block, b, p or k for the previous block.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 1497x                   7x         7x                                                                         7x                           7x                                                 226x 689x 226x 226x 225x 224x 223x 222x 293x 1x 233x 1x 290x 1x 218x           864x 864x 6x   212x     308x     10x     10x             10x 4x 4x 2x 1x     6x 6x 5x 4x 3x 1x 2x 1x      
export const TONE_MAPPING_OPTIONS = [
  { value: 'aces', label: 'ACES Filmic' },
  { value: 'agx', label: 'AgX' },
  { value: 'neutral', label: 'Neutral' },
  { value: 'reinhard', label: 'Reinhard' },
  { value: 'cineon', label: 'Cineon' },
  { value: 'linear', label: 'Linear' },
  { value: 'none', label: 'None' },
] as const;
export type ToneMappingName = (typeof TONE_MAPPING_OPTIONS)[number]['value'];
export const VIEW_MODE_OPTIONS = [
  { value: 'realistic', label: 'Realistic' },
  { value: 'measurement', label: 'Measurement' },
] as const;
export type ViewMode = (typeof VIEW_MODE_OPTIONS)[number]['value'];
export const UNITS_OPTIONS = [
  { value: 'metric', label: 'Metric' },
  { value: 'imperial', label: 'Imperial' },
] as const;
export type Units = (typeof UNITS_OPTIONS)[number]['value'];
/** Scene and display settings shared by the React viewer and `<light-viewer>`. */
export interface ViewerSettings {
  /** Show the back wall. Defaults to true. */
  showWall: boolean;
  /** Wall distance from the luminaire in meters. Defaults to 2. */
  wallDistance: number;
  /** Floor distance below the luminaire in meters. Defaults to 2. */
  floorDistance: number;
  /**
   * Sideways offset of the luminaire along the wall in meters, from -100 to 100. Defaults to 0.
   * @deprecated Moving along the wall changes nothing meaningful; the panel, drags and arrow keys no longer set it.
   * Still honoured when set; it will be removed in the next major version.
   */
  lightOffset: number;
  /** Tone mapping operator. Defaults to `aces`. */
  toneMapping: ToneMappingName;
  /** Meter the exposure from the peak floor/wall luminance and report it in `exposure`. Defaults to true. */
  autoExposure: boolean;
  /** Camera exposure value EV100, -6 to 20: luminance 1.2 · 2^EV100 cd/m² displays as 1 before tone mapping.
   * Used when `autoExposure` is false; otherwise set by the viewer to the metered value. Defaults to 6. */
  exposure: number;
  /** Show the blue beam-extent helper lines (cone or spheres). Defaults to true. */
  helper: boolean;
  /** `realistic` shades diffuse surfaces; `measurement` shows false-colour illuminance with isolux contours. Defaults to `realistic`. */
  viewMode: ViewMode;
  /** Display units: lux and metres, or footcandles and feet. Stored distances stay in metres. Defaults to `metric`. */
  units: Units;
  /** Overlay the 3D candela distribution, its peak at half the floor distance. Defaults to false. */
  photometricSolid: boolean;
  /** Show floor distance rulers and the mounting-height ruler. Defaults to true. */
  rulers: boolean;
}
export const DEFAULT_VIEWER_SETTINGS: Readonly<ViewerSettings> = Object.freeze({
  showWall: true,
  wallDistance: 2,
  floorDistance: 2,
  lightOffset: 0,
  toneMapping: 'aces',
  autoExposure: true,
  exposure: 6,
  helper: true,
  viewMode: 'realistic',
  units: 'metric',
  photometricSolid: false,
  rulers: true,
});
export const VIEWER_SETTINGS_ATTRIBUTES = [
  'show-wall',
  'wall-distance',
  'floor-distance',
  'light-offset',
  'tone-mapping',
  'auto-exposure',
  'exposure',
  'helper',
  'view-mode',
  'units',
  'photometric-solid',
  'rulers',
] as const;
export interface ViewerSettingsChangeDetail {
  settings: ViewerSettings;
  previousSettings: ViewerSettings;
}
export type ViewerSettingsListener = (event: CustomEvent<ViewerSettingsChangeDetail>) => void;
 
/** Validate the whole patch before publishing a new state. No partial mutations or silent clamping. */
export function resolveViewerSettings(
  patch: Partial<ViewerSettings>,
  current: Readonly<ViewerSettings> = DEFAULT_VIEWER_SETTINGS,
): ViewerSettings {
  for (const key of Object.keys(patch))
    Iif (!Object.hasOwn(DEFAULT_VIEWER_SETTINGS, key)) throw new Error(`Unknown viewer setting: ${key}`);
  const next = { ...current, ...patch };
  if (typeof next.showWall !== 'boolean') throw new TypeError('showWall must be a boolean');
  if (typeof next.helper !== 'boolean') throw new TypeError('helper must be a boolean');
  if (typeof next.photometricSolid !== 'boolean') throw new TypeError('photometricSolid must be a boolean');
  if (typeof next.rulers !== 'boolean') throw new TypeError('rulers must be a boolean');
  if (typeof next.autoExposure !== 'boolean') throw new TypeError('autoExposure must be a boolean');
  if (!TONE_MAPPING_OPTIONS.some((option) => option.value === next.toneMapping))
    throw new RangeError('Unsupported toneMapping function');
  if (!VIEW_MODE_OPTIONS.some((option) => option.value === next.viewMode))
    throw new RangeError('viewMode must be realistic or measurement');
  if (!UNITS_OPTIONS.some((option) => option.value === next.units))
    throw new RangeError('units must be metric or imperial');
  for (const [key, min, max] of [
    ['wallDistance', 0.1, 100],
    ['floorDistance', 0.1, 100],
    ['lightOffset', -100, 100],
    ['exposure', -6, 20],
  ] as const) {
    const value = next[key];
    if (!Number.isFinite(value) || value < min || value > max)
      throw new RangeError(`${key} must be a finite number from ${min} to ${max}`);
  }
  return next;
}
export function settingsEqual(a: Readonly<ViewerSettings>, b: Readonly<ViewerSettings>): boolean {
  return (Object.keys(DEFAULT_VIEWER_SETTINGS) as (keyof ViewerSettings)[]).every((key) => a[key] === b[key]);
}
export function viewerSettingFromAttribute(name: string, value: string | null): Partial<ViewerSettings> {
  const number = (key: 'wallDistance' | 'floorDistance' | 'lightOffset' | 'exposure') => ({
    [key]: value === null ? DEFAULT_VIEWER_SETTINGS[key] : value.trim() ? Number(value) : NaN,
  });
  const booleans = {
    'show-wall': 'showWall',
    helper: 'helper',
    'photometric-solid': 'photometricSolid',
    rulers: 'rulers',
    'auto-exposure': 'autoExposure',
  } as const;
  if (Object.hasOwn(booleans, name)) {
    const key = booleans[name as keyof typeof booleans];
    if (value === null) return { [key]: DEFAULT_VIEWER_SETTINGS[key] };
    if (value === '' || value === 'true') return { [key]: true };
    Eif (value === 'false') return { [key]: false };
    throw new RangeError(`${name} must be empty, true, or false`);
  }
  Iif (name === 'wall-distance') return number('wallDistance');
  if (name === 'floor-distance') return number('floorDistance');
  if (name === 'light-offset') return number('lightOffset');
  if (name === 'exposure') return number('exposure');
  if (name === 'tone-mapping')
    return { toneMapping: (value ?? DEFAULT_VIEWER_SETTINGS.toneMapping) as ToneMappingName };
  if (name === 'view-mode') return { viewMode: (value ?? DEFAULT_VIEWER_SETTINGS.viewMode) as ViewMode };
  Eif (name === 'units') return { units: (value ?? DEFAULT_VIEWER_SETTINGS.units) as Units };
  return {};
}