@xgis/xgis3d 0.3.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +144 -0
  3. package/dist/Map3D.d.ts +7 -0
  4. package/dist/cameraBoundsGuard.d.ts +6 -0
  5. package/dist/cameraScale.d.ts +7 -0
  6. package/dist/capabilities/cesiumCamera.d.ts +17 -0
  7. package/dist/capabilities/cesiumEngineHealth.d.ts +6 -0
  8. package/dist/capabilities/cesiumViewLimits.d.ts +3 -0
  9. package/dist/cesiumBaseUrl.d.ts +6 -0
  10. package/dist/entryCamera.d.ts +20 -0
  11. package/dist/index.d.ts +3 -0
  12. package/dist/index.js +1460 -0
  13. package/dist/index.js.map +1 -0
  14. package/dist/interactions/canvasPressRelay.d.ts +2 -0
  15. package/dist/interactions/cesiumKeyboardHandler.d.ts +5 -0
  16. package/dist/interactions/nadirLimit.d.ts +8 -0
  17. package/dist/pickGroundPoint.d.ts +5 -0
  18. package/dist/projection.d.ts +46 -0
  19. package/dist/reconcilers/useCesiumBasemapAttachments.d.ts +11 -0
  20. package/dist/reconcilers/useCesiumBasemapReconciler.d.ts +2 -0
  21. package/dist/reconcilers/useCesiumEntryCamera.d.ts +9 -0
  22. package/dist/reconcilers/useCesiumLayerReconciler.d.ts +2 -0
  23. package/dist/reconcilers/useCesiumTerrainReconciler.d.ts +2 -0
  24. package/dist/reconcilers/useCesiumUserMarker.d.ts +2 -0
  25. package/dist/reconcilers/useCesiumViewBounds.d.ts +3 -0
  26. package/dist/utils/create3DTilesetLayer.d.ts +10 -0
  27. package/dist/utils/createKMLLayer.d.ts +9 -0
  28. package/dist/utils/createOGCMapsLayer.d.ts +3 -0
  29. package/dist/utils/createOGCTilesLayer.d.ts +3 -0
  30. package/dist/utils/createTMSLayer.d.ts +3 -0
  31. package/dist/utils/createWMSLayer.d.ts +3 -0
  32. package/dist/utils/createWMTSLayer.d.ts +3 -0
  33. package/dist/utils/kmlEntityOpacity.d.ts +15 -0
  34. package/dist/utils/kmlEntityStyle.d.ts +4 -0
  35. package/dist/utils/layerCreation.d.ts +15 -0
  36. package/dist/utils/safeMinimumLevel.d.ts +3 -0
  37. package/package.json +62 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Republic of Estonia Land and Spatial Development Board
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,144 @@
1
+ # @xgis/xgis3d
2
+
3
+ CesiumJS 3D map engine for XGIS3D. Renders the globe, implements engine capabilities, and reconciles
4
+ layers and terrain from the shared stores. It is not a standalone map — it is loaded by
5
+ [`@xgis/xgis`](../xgis/README.md) when `mapMode` is `'3d'` or `'both'`.
6
+
7
+ Part of the [XGIS3D monorepo](../../README.md).
8
+
9
+ ## Do not import this directly
10
+
11
+ Consumers call `mountXgis()` and set `mapMode`; the host lazy-loads this package on demand
12
+ ([ADR-0001](../../docs/decisions/0001-host-centric-mount-over-standalone-remotes.md)). The laziness
13
+ matters here — Cesium ships about 7 MB of runtime assets, plus a ~4.6 MB JavaScript chunk, that a 2D-only user should never fetch.
14
+
15
+ ```bash
16
+ pnpm add @xgis/xgis3d
17
+ ```
18
+
19
+ ## How it fits
20
+
21
+ ```
22
+ mapViewStore / layerStore / terrainStore (@xgis/xgis-common)
23
+ │
24
+ coordinators
25
+ │
26
+ Map3D ──registers──► MapAdapter
27
+ │
28
+ Cesium Viewer (via resium)
29
+ ```
30
+
31
+ ## Cesium runtime assets
32
+
33
+ Cesium loads workers, textures and widget CSS **at runtime**, by URL. A bundler bundles the
34
+ JavaScript but never sees those files, so they have to be served separately — and Cesium has to be
35
+ told where.
36
+
37
+ That is not this package's job. [`@xgis/xgis3d-build`](../xgis3d-build/README.md) does it, with a
38
+ Vite plugin, an Rspack plugin and a CLI for everything else. It resolves Cesium _through_ this
39
+ package, so the assets it serves are always the exact copy this runtime was built against
40
+ ([ADR-0022](../../docs/decisions/0022-bundler-agnostic-cesium-assets.md)).
41
+
42
+ ```bash
43
+ pnpm add -D @xgis/xgis3d-build
44
+ ```
45
+
46
+ This package keeps only the runtime half:
47
+
48
+ ### The runtime default
49
+
50
+ Importing `@xgis/xgis3d` sets `window.CESIUM_BASE_URL` to `/cesium-<version>` if nothing has set it
51
+ already. This happens as an import side effect, before Cesium can resolve its first asset URL. If
52
+ you set the global yourself — in HTML, or via the plugin's `base` — yours wins.
53
+
54
+ `ensureCesiumBaseUrl()` is also exported for consumers that need to run it explicitly.
55
+
56
+ > If the globe renders but tiles, terrain or the widget chrome are missing, the two halves disagree:
57
+ > check that the directory the plugin wrote matches the value of `window.CESIUM_BASE_URL`.
58
+
59
+ ### Licensing of the copied assets
60
+
61
+ Copying those directories into a deployed site is redistribution of CesiumJS, which is Apache-2.0.
62
+ `@xgis/xgis3d-build` therefore also copies Cesium's `LICENSE.md` alongside them, into
63
+ `dist/cesium-<version>/LICENSE.md`. That one file carries the Apache-2.0 text and the notices for
64
+ the 28 third-party components Cesium embeds, so it discharges both Apache-2.0 section 4(a) and the
65
+ BSD-3-Clause reproduction requirement for the files under `ThirdParty/`. Because it is read from
66
+ whichever Cesium is installed, it stays correct across upgrades with nothing to maintain.
67
+
68
+ If you serve the assets from your own location instead of using that package, copy that file too.
69
+
70
+ Three findings from a licensing review, recorded here so nobody has to re-derive them:
71
+
72
+ - **Apache-2.0 section 4(d) does not apply.** It only bites when the licensed work ships a `NOTICE`
73
+ file, and Cesium ships none — checked across every Apache-2.0 package in the runtime graph. The
74
+ files are also copied unmodified, so section 4(b) does not apply either. Section 4(a) is the only
75
+ live requirement, and copying `LICENSE.md` meets it.
76
+ - **DOMPurify's dual licence is already resolved.** Cesium embeds it, and it is offered under
77
+ `MPL-2.0 OR Apache-2.0`. Cesium elects Apache-2.0, recorded in `ThirdParty.json` in the Cesium
78
+ package. Composition analysis tooling reports the dual expression and flags `MPL-2.0`; that
79
+ election is the answer, and no MPL obligation reaches this project.
80
+ - **The navigation help icons need visible credit.** `Widgets/Images/NavigationHelp/*.svg` are by
81
+ Freepik from Flaticon.com under Creative Commons Attribution 3.0. They are part of the library
82
+ build and the plugin copies `Widgets` unconditionally, so the obligation attaches on distribution
83
+ rather than only when the widget is displayed. The copied `LICENSE.md` carries the credit.
84
+
85
+ Nothing third-party is bundled into this package itself — `vite.lib.config.ts` externalises every
86
+ bare specifier, so Cesium reaches you as its own npm package with its own licence file. These
87
+ obligations belong to the application you deploy, not to the tarball.
88
+
89
+ ## What lives here
90
+
91
+ | Path | Description |
92
+ | ------------------ | ---------------------------------------------------------------------- |
93
+ | `Map3D.tsx` | The React component; creates the Cesium `Viewer`, registers the engine |
94
+ | `capabilities/` | `cesiumCamera` (`ICameraCapability`) and `cesiumEngineHealth` |
95
+ | `reconcilers/` | Shallow-diff store state onto imagery layers, primitives, data sources |
96
+ | `interactions/` | Pointer and picking behaviour |
97
+ | `projection.ts` | EPSG:3301 ↔ globe projection handling |
98
+ | `cesiumBaseUrl.ts` | The runtime `window.CESIUM_BASE_URL` default |
99
+
100
+ ## Dependency policy
101
+
102
+ `cesium` and `resium` are **exact-pinned dependencies**, not peers. Cesium does not follow
103
+ semver — a majority of its minor releases carry breaking changes — so this package pins the one
104
+ version it is tested against. A consumer does not choose the Cesium version; if it needs to change,
105
+ the change belongs here.
106
+
107
+ ### Bumping Cesium
108
+
109
+ `@cesium/engine` and `@cesium/widgets` are pinned here too, and **all three move together**.
110
+
111
+ `cesium` re-exports around 1300 symbols from `@cesium/engine` but declares only a caret range on it.
112
+ Engine minors have removed symbols `cesium` still re-exports — 26.3.0 dropped the ClippingPolygons
113
+ shaders that `cesium@1.143.0` re-exports — and a published package cannot ship a lockfile, so every
114
+ consumer re-resolves that range and gets whichever engine is newest. The mismatch passes
115
+ `vite build`, which drops the missing exports silently, and breaks `vite dev` and Rspack, which
116
+ reject them. Pinning here is the last place the combination can be fixed for everyone downstream.
117
+
118
+ To bump, take the versions from the release you are moving to rather than choosing them:
119
+
120
+ ```bash
121
+ npm view cesium@<version> dependencies
122
+ ```
123
+
124
+ Copy the `@cesium/engine` and `@cesium/widgets` versions it names, dropping the caret, then run
125
+ `pnpm test` in this package. `cesiumDependencies.test.ts` checks every symbol `cesium` re-exports
126
+ against the installed engine and fails on a mismatched pair, so a wrong combination stops in CI
127
+ instead of in someone's dev server.
128
+
129
+ There are no build-tool peers here any more. `vite`, `@rspack/core` and `sirv` moved to
130
+ [`@xgis/xgis3d-build`](../xgis3d-build/README.md) with the plugins, so installing the 3D engine no
131
+ longer drags a Node static-file server into your dependency graph.
132
+
133
+ `./package.json` is exported so `@xgis/xgis3d-build` can resolve this package's Cesium. Do not rely
134
+ on it for anything else.
135
+
136
+ ## Docs
137
+
138
+ - [Architecture overview](../../docs/architecture.md) — basemap attachment and teardown is section 8
139
+ - [Developer guide](../../docs/developer-guide.md) — engine and capability system, sections 7–8
140
+ - [ADRs](../../docs/decisions/)
141
+
142
+ ## License
143
+
144
+ MIT — see [LICENSE](./LICENSE).
@@ -0,0 +1,7 @@
1
+ import 'cesium/Build/Cesium/Widgets/widgets.css';
2
+ import type { EngineRegistration, IMapEngine } from '@xgis/xgis-common';
3
+ interface Map3DProps {
4
+ onEngineReady: (engine: IMapEngine) => EngineRegistration;
5
+ }
6
+ export declare function Map3D({ onEngineReady }: Map3DProps): import("react/jsx-runtime").JSX.Element;
7
+ export {};
@@ -0,0 +1,6 @@
1
+ import type { Extent3301, ZoomLevel } from '@xgis/xgis-common';
2
+ import type { Viewer as CesiumViewer } from 'cesium';
3
+ /** Zoom at which `bounds` just fills the canvas — the furthest this camera may pull back. */
4
+ export declare function boundsFloor(viewer: CesiumViewer, bounds: Extent3301): ZoomLevel;
5
+ /** Cesium has no extent constraint, so the camera is pulled back each frame after it moves. */
6
+ export declare function createCameraBoundsGuard(viewer: CesiumViewer, bounds: Extent3301): () => void;
@@ -0,0 +1,7 @@
1
+ import type { ZoomLevel } from '@xgis/xgis-common';
2
+ import type { Viewer as CesiumViewer } from 'cesium';
3
+ /** Camera→focus range that renders `zoom` at the same ground scale as the 2D map. */
4
+ export declare function rangeForZoom(viewer: CesiumViewer, zoom: number): number;
5
+ /** The 2D zoom whose resolution matches the ground scale at `range` — inverse of `rangeForZoom`. */
6
+ export declare function zoomForRange(viewer: CesiumViewer, range: number): number;
7
+ export declare function reportedZoomGrid(zoom: number): ZoomLevel;
@@ -0,0 +1,17 @@
1
+ import type { ICameraCapability } from '@xgis/xgis-common';
2
+ import type { Camera, Viewer as CesiumViewer } from 'cesium';
3
+ interface CameraFocus {
4
+ readonly lon: number;
5
+ readonly lat: number;
6
+ readonly height: number;
7
+ readonly range: number;
8
+ readonly onTerrain: boolean;
9
+ }
10
+ export declare const MAX_FOCUS_RANGE_FACTOR = 10;
11
+ export declare function screenCenterGroundFocus(viewer: CesiumViewer): CameraFocus | undefined;
12
+ export declare function headingPitchAtFocus(camera: Camera, lon: number, lat: number): {
13
+ heading: number;
14
+ pitch: number;
15
+ };
16
+ export declare function createCesiumCameraCapability(viewer: CesiumViewer): ICameraCapability;
17
+ export {};
@@ -0,0 +1,6 @@
1
+ import { type EngineErrorChannel } from '@xgis/xgis-common';
2
+ import type { Viewer as CesiumViewer } from 'cesium';
3
+ export interface CesiumEngineHealth extends EngineErrorChannel {
4
+ dispose(): void;
5
+ }
6
+ export declare function createCesiumEngineHealth(viewer: CesiumViewer): CesiumEngineHealth;
@@ -0,0 +1,3 @@
1
+ import type { IViewLimitsCapability } from '@xgis/xgis-common';
2
+ import type { Viewer as CesiumViewer } from 'cesium';
3
+ export declare function createCesiumViewLimitsCapability(viewer: CesiumViewer): IViewLimitsCapability;
@@ -0,0 +1,6 @@
1
+ declare global {
2
+ interface Window {
3
+ CESIUM_BASE_URL?: string;
4
+ }
5
+ }
6
+ export declare function ensureCesiumBaseUrl(): void;
@@ -0,0 +1,20 @@
1
+ import type { Extent3301, Radians, ZoomLevel } from '@xgis/xgis-common';
2
+ import type { TerrainProvider, Viewer as CesiumViewer } from 'cesium';
3
+ export declare const ELLIPSOID_HEIGHT = 0;
4
+ export interface EntryView {
5
+ readonly bbox: Extent3301;
6
+ readonly zoom: ZoomLevel;
7
+ readonly rotation: Radians;
8
+ readonly pitch: Radians;
9
+ }
10
+ export interface EntryTarget {
11
+ readonly lon: number;
12
+ readonly lat: number;
13
+ readonly heading: number;
14
+ readonly pitch: number;
15
+ readonly range: number;
16
+ }
17
+ export declare function entryTarget(viewer: CesiumViewer, view: EntryView): EntryTarget;
18
+ export declare function placeEntryCamera(viewer: CesiumViewer, target: EntryTarget, height: number): void;
19
+ export declare function raiseEntryCameraToTerrain(viewer: CesiumViewer, target: EntryTarget, height: number): void;
20
+ export declare function sampleEntryHeight(provider: TerrainProvider, target: EntryTarget): Promise<number | undefined>;
@@ -0,0 +1,3 @@
1
+ import './cesiumBaseUrl';
2
+ export { ensureCesiumBaseUrl } from './cesiumBaseUrl';
3
+ export { Map3D } from './Map3D';