@xgis/xgis3d 0.3.23 → 0.3.35

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/README.md CHANGED
@@ -1,16 +1,14 @@
1
1
  # @xgis/xgis3d
2
2
 
3
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).
4
+ layers and terrain from the shared stores. The host
5
+ [`@xgis/xgis`](https://www.npmjs.com/package/@xgis/xgis) loads it when `mapMode` is `'3d'` or
6
+ `'both'`; it is not used on its own.
8
7
 
9
8
  ## Do not import this directly
10
9
 
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.
10
+ Consumers call `mountXgis()` and set `mapMode`; the host loads this package on demand, so a
11
+ 2D-only user never fetches Cesium's ~7 MB of runtime assets or its ~4.6 MB JavaScript chunk.
14
12
 
15
13
  ```bash
16
14
  pnpm add @xgis/xgis3d
@@ -31,114 +29,52 @@ pnpm add @xgis/xgis3d
31
29
  ## Cesium runtime assets
32
30
 
33
31
  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
32
+ JavaScript but never sees those files, so they have to be served separately, and Cesium has to be
35
33
  told where.
36
34
 
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)).
35
+ [`@xgis/xgis3d-build`](https://www.npmjs.com/package/@xgis/xgis3d-build) does that, with a Vite
36
+ plugin, an Rspack plugin and a CLI for everything else. It resolves Cesium through this package, so
37
+ the assets it serves are always the copy this runtime was built against.
41
38
 
42
39
  ```bash
43
40
  pnpm add -D @xgis/xgis3d-build
44
41
  ```
45
42
 
46
- This package keeps only the runtime half:
43
+ This package handles the runtime side:
47
44
 
48
45
  ### The runtime default
49
46
 
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.
47
+ Importing `@xgis/xgis3d` reads `<meta name="xgis-cesium-base-url">` and falls back to
48
+ `/cesium-<version>`. This happens as an import side effect, before Cesium can resolve its first
49
+ asset URL. The build plugin emits the tag; set it yourself only if you copy the assets by hand.
53
50
 
54
51
  `ensureCesiumBaseUrl()` is also exported for consumers that need to run it explicitly.
55
52
 
56
53
  > 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`.
54
+ > check that the directory the plugin wrote matches the meta tag in your HTML.
58
55
 
59
56
  ### Licensing of the copied assets
60
57
 
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 |
58
+ Copying Cesium's assets into a deployed site redistributes CesiumJS, which is Apache-2.0.
59
+ `@xgis/xgis3d-build` copies Cesium's `LICENSE.md` alongside them, which discharges the obligation.
60
+ If you serve the assets from your own location instead, copy that file too.
99
61
 
100
62
  ## Dependency policy
101
63
 
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:
64
+ `cesium` and `resium` are **exact-pinned dependencies**, not peers. Cesium does not follow semver, so this package pins the
65
+ version it is tested against. A consumer does not choose the Cesium version.
119
66
 
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.
67
+ `@cesium/engine` and `@cesium/widgets` are pinned alongside `cesium` and move together. `cesium`
68
+ depends on the engine with a caret range while re-exporting around 1300 of its symbols, and engine
69
+ minors have removed symbols `cesium` still re-exports, so the three are pinned as a set.
128
70
 
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.
71
+ This package has no build-tool peers. `vite`, `@rspack/core` and `sirv` live in
72
+ `@xgis/xgis3d-build`, so installing the 3D engine does not pull a Node static-file server into your
73
+ dependency graph.
132
74
 
133
75
  `./package.json` is exported so `@xgis/xgis3d-build` can resolve this package's Cesium. Do not rely
134
76
  on it for anything else.
135
77
 
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
78
  ## License
143
79
 
144
- MIT — see [LICENSE](./LICENSE).
80
+ MIT. See the LICENSE file in this package.
package/dist/Map3D.d.ts CHANGED
@@ -1,5 +1,7 @@
1
1
  import 'cesium/Build/Cesium/Widgets/widgets.css';
2
2
  import type { EngineRegistration, IMapEngine } from '@xgis/xgis-common';
3
+ import type { Viewer as CesiumViewer } from 'cesium';
4
+ export declare function applyRotationPermission(viewer: CesiumViewer, rotationAllowed: boolean): void;
3
5
  interface Map3DProps {
4
6
  onEngineReady: (engine: IMapEngine) => EngineRegistration;
5
7
  }
@@ -1,5 +1,5 @@
1
1
  import type { ICameraCapability } from '@xgis/xgis-common';
2
- import type { Camera, Viewer as CesiumViewer } from 'cesium';
2
+ import type { Camera, TerrainProvider, Viewer as CesiumViewer } from 'cesium';
3
3
  interface CameraFocus {
4
4
  readonly lon: number;
5
5
  readonly lat: number;
@@ -13,5 +13,9 @@ export declare function headingPitchAtFocus(camera: Camera, lon: number, lat: nu
13
13
  heading: number;
14
14
  pitch: number;
15
15
  };
16
+ export declare function sampleTerrainHeight(provider: TerrainProvider, position: {
17
+ lon: number;
18
+ lat: number;
19
+ }): Promise<number | undefined>;
16
20
  export declare function createCesiumCameraCapability(viewer: CesiumViewer): ICameraCapability;
17
21
  export {};
@@ -3,4 +3,9 @@ declare global {
3
3
  CESIUM_BASE_URL?: string;
4
4
  }
5
5
  }
6
+ /**
7
+ * Under Module Federation the base URL is baked in by a `define`. An npm consumer gets the meta tag
8
+ * from the cesiumAssets build plugin. This default is the remaining case: assets copied to the
9
+ * conventional path without the plugin.
10
+ */
6
11
  export declare function ensureCesiumBaseUrl(): void;
@@ -1,5 +1,5 @@
1
- import type { Extent3301, Radians, ZoomLevel } from '@xgis/xgis-common';
2
- import type { TerrainProvider, Viewer as CesiumViewer } from 'cesium';
1
+ import { type Extent3301, type Radians, type ZoomLevel } from '@xgis/xgis-common';
2
+ import { type Viewer as CesiumViewer } from 'cesium';
3
3
  export declare const ELLIPSOID_HEIGHT = 0;
4
4
  export interface EntryView {
5
5
  readonly bbox: Extent3301;
@@ -17,4 +17,3 @@ export interface EntryTarget {
17
17
  export declare function entryTarget(viewer: CesiumViewer, view: EntryView): EntryTarget;
18
18
  export declare function placeEntryCamera(viewer: CesiumViewer, target: EntryTarget, height: number): void;
19
19
  export declare function raiseEntryCameraToTerrain(viewer: CesiumViewer, target: EntryTarget, height: number): void;
20
- export declare function sampleEntryHeight(provider: TerrainProvider, target: EntryTarget): Promise<number | undefined>;