@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.
- package/LICENSE +21 -0
- package/README.md +144 -0
- package/dist/Map3D.d.ts +7 -0
- package/dist/cameraBoundsGuard.d.ts +6 -0
- package/dist/cameraScale.d.ts +7 -0
- package/dist/capabilities/cesiumCamera.d.ts +17 -0
- package/dist/capabilities/cesiumEngineHealth.d.ts +6 -0
- package/dist/capabilities/cesiumViewLimits.d.ts +3 -0
- package/dist/cesiumBaseUrl.d.ts +6 -0
- package/dist/entryCamera.d.ts +20 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +1460 -0
- package/dist/index.js.map +1 -0
- package/dist/interactions/canvasPressRelay.d.ts +2 -0
- package/dist/interactions/cesiumKeyboardHandler.d.ts +5 -0
- package/dist/interactions/nadirLimit.d.ts +8 -0
- package/dist/pickGroundPoint.d.ts +5 -0
- package/dist/projection.d.ts +46 -0
- package/dist/reconcilers/useCesiumBasemapAttachments.d.ts +11 -0
- package/dist/reconcilers/useCesiumBasemapReconciler.d.ts +2 -0
- package/dist/reconcilers/useCesiumEntryCamera.d.ts +9 -0
- package/dist/reconcilers/useCesiumLayerReconciler.d.ts +2 -0
- package/dist/reconcilers/useCesiumTerrainReconciler.d.ts +2 -0
- package/dist/reconcilers/useCesiumUserMarker.d.ts +2 -0
- package/dist/reconcilers/useCesiumViewBounds.d.ts +3 -0
- package/dist/utils/create3DTilesetLayer.d.ts +10 -0
- package/dist/utils/createKMLLayer.d.ts +9 -0
- package/dist/utils/createOGCMapsLayer.d.ts +3 -0
- package/dist/utils/createOGCTilesLayer.d.ts +3 -0
- package/dist/utils/createTMSLayer.d.ts +3 -0
- package/dist/utils/createWMSLayer.d.ts +3 -0
- package/dist/utils/createWMTSLayer.d.ts +3 -0
- package/dist/utils/kmlEntityOpacity.d.ts +15 -0
- package/dist/utils/kmlEntityStyle.d.ts +4 -0
- package/dist/utils/layerCreation.d.ts +15 -0
- package/dist/utils/safeMinimumLevel.d.ts +3 -0
- 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).
|
package/dist/Map3D.d.ts
ADDED
|
@@ -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,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>;
|
package/dist/index.d.ts
ADDED