@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 +26 -90
- package/dist/Map3D.d.ts +2 -0
- package/dist/capabilities/cesiumCamera.d.ts +5 -1
- package/dist/cesiumBaseUrl.d.ts +5 -0
- package/dist/entryCamera.d.ts +2 -3
- package/dist/index.js +251 -46
- package/dist/index.js.map +1 -1
- package/dist/interactions/centroidTilt.d.ts +12 -0
- package/dist/reconcilers/userMarkerCone.d.ts +5 -0
- package/package.json +5 -5
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.
|
|
5
|
-
[`@xgis/xgis`](
|
|
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
|
|
12
|
-
|
|
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
|
|
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
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
|
43
|
+
This package handles the runtime side:
|
|
47
44
|
|
|
48
45
|
### The runtime default
|
|
49
46
|
|
|
50
|
-
Importing `@xgis/xgis3d`
|
|
51
|
-
|
|
52
|
-
|
|
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
|
|
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
|
|
62
|
-
`@xgis/xgis3d-build`
|
|
63
|
-
|
|
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
|
-
|
|
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
|
-
|
|
121
|
-
|
|
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
|
-
|
|
130
|
-
|
|
131
|
-
|
|
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
|
|
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 {};
|
package/dist/cesiumBaseUrl.d.ts
CHANGED
|
@@ -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;
|
package/dist/entryCamera.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import type
|
|
2
|
-
import
|
|
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>;
|