EHR 3D Twin library component
The 3D Map of Estonia.
Prerequisites
React
The library plays the role of a React component, the following libraries must be present in the project:
"react": "18.2.0"
"react-dom": "18.2.0"
- Note: The versions are inherited from
ehr-components
library.
EHR related
The library is developed to work inside the EHR application ecosystem, thus the following libraries must also be present:
"ehr-components": "0.x"
"react-intl": "5.8.5"
Quickstart
All previous dependencies can be installed (e.g. on a fresh project) using yarn add react react-dom ehr-components react-intl
Installation
1. Install the dependencies
yarn add ehr-3d-twin cesium
2. Expose CESIUM_BASE_URL
The Easiest way (CDN)
Importing Cesium CDN into the head of the public/index.html
<script src="https://cesium.com/downloads/cesiumjs/releases/1.77/Build/Cesium/Cesium.js"></script>
<link href="https://cesium.com/downloads/cesiumjs/releases/1.77/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
Easy way (Craco)
Extend the configuration for react-scripts to serve cesium for you.
-
Install Craco yarn add @craco/craco craco-cesium
-
Change scripts in package.json
"scripts": {
"start": "craco start",
"build": "craco build",
"test": "craco test",
"eject": "react-scripts eject"
},
-
Create the Craco configuration file in the root of the project craco.config.js
-
Extend the Cesium configuration, add this code inside the file:
module.exports = {
plugins: [
{
plugin: require("craco-cesium")()
}
]
};
More information on this method
Statically serve the cesium built files with custom bundler
- Copy cesium static files into
/public
node_modules/cesium/Build/Cesium/Workers
node_modules/cesium/Build/Cesium/ThirdParty
node_modules/cesium/Build/Cesium/Assets
node_modules/cesium/Build/Cesium/Widgets
node_modules/cesium/Build/Cesium/Cesium.js
- Configure the application bundler to serve these files
- Set the CESIUM_BASE_URL to point to the serving location (e.g.
window.CESIUM_BASE_URL = '/';
) This should be the first line of code - Import cesium into the project
import * as Cesium from 'cesium';
import "cesium/Build/Cesium/Widgets/widgets.css";
More information on this method
Usage
import {Controls, Entities, Map3D} from "ehr-3d-twin";
import {IntlProvider} from "react-intl";
import messages from './lang/et-EE.json';
<IntlProvider locale='et' messages={messages}>
<Map3D>
<Controls />
<Entities />
</Map3D>
</IntlProvider>
Note: The mta styles should be also included for the application to look as expected.
Typescript is fully supported.
Props
Required props should be passed on <Map3D />
.
Prop | Type | Description | Example |
---|
config | Map3DProps | Sets the initial state of the component. The urls for the external services are required. | { base: { urls: { APP: 'http://localhost:3000', APP_1: 'http://localhost:3000', APP_2: 'http://localhost:3000', APP_3: 'http://localhost:3000', APP_4: 'http://localhost:3000', APP_ENDING: '/', GEOPORTAL: 'http://localhost:3000/index.php', MAAMET: 'https://www.maaamet.ee/et', MAAMET_MAP: 'https://kaart.maaamet.ee', MAAMET_TILES: 'https://tiles.maaamet.ee', MAAMET_XGIS: 'https://xgis.maaamet.ee', KINNISTUSRAAMAT: 'https://kinnistusraamat.rik.ee', GSAVALIK: 'https://gsavalik.envir.ee' } } } |
Full list of supported initial configurations:
config: {
layers?: {
layers2D?: {
showAdministrationUnits?: {
showing: boolean,
transparency: 100,
},
showBridges?: {
showing: boolean,
transparency: 100,
},
showCadastres?: {
showing: boolean,
transparency: 100,
},
showGeology?: {
showing: boolean,
transparency: 100,
},
showKPO?: {
showing: boolean,
transparency: 100,
},
showKPOWater?: {
showing: boolean,
transparency: 100,
},
showKPOEnvironment?: {
showing: boolean,
transparency: 100,
},
showKPOTechno?: {
showing: boolean,
transparency: 100,
},
showKPOOther?: {
showing: boolean,
transparency: 100,
},
showRoads?: {
showing: boolean,
transparency: 100,
},
showTraps?: {
showing: boolean,
transparency: 100,
},
showTrafficRoads?: {
showing: boolean,
transparency: 100,
},
showNoiseWalls?: {
showing: boolean,
transparency: 100,
},
showBusStops?: {
showing: boolean,
transparency: 100,
},
showExits?: {
showing: boolean,
transparency: 100,
},
showCrossings?: {
showing: boolean,
transparency: 100,
},
showHydrants?: {
showing: boolean,
transparency: 100,
},
showWaterSources?: {
showing: boolean,
transparency: 100,
},
showTileSquares?: {
showing: boolean,
transparency: 100,
},
},
layers3D?: {
showAirzone?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showVegetation?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showTerrain?: boolean,
showLOD1?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showLOD2?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showLOD3?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showOldTown?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showFloodMap1?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showFloodMap10?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showFloodMap50?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showFloodMap100?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showFloodMap1000?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showRiskAreas?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showUtilities?: {
transparency: 0 | 25 | 50 | 75 | 100,
showing: boolean,
},
showColorHeights?: boolean,
showColorByUsage?: boolean,
showLabels?: boolean,
showShadows?: boolean,
excludedEhrCodes?: string[],
},
},
functionalities?: {
showDistanceMeasurement?: boolean,
showMeasurement3D?: boolean,
showDownloadBox?: boolean,
},
base: {
showOnBoarding?: boolean,
transparencyCanShow?: boolean,
urls: {
APP: string,
APP_1: string,
APP_2: string,
APP_3: string,
APP_4: string,
APP_ENDING: string,
GEOPORTAL: string,
MAAMET: string,
MAAMET_MAP: string,
MAAMET_TILES: string,
MAAMET_XGIS: string,
KINNISTUSRAAMAT: string,
GSAVALIK: string,
PLANK: string
},
},
customBuildings?: {
userFiles?: {
files: EditableCustomFile[],
filesProcessing: ToggleableAlert[],
filesFailed: ToggleableAlert[],
filesSucceeded: ToggleableAlert[],
},
sharedFiles?: CustomFile[],
sharedCodes?: string[],
},
ui?: {
layersPanelOpen?: boolean,
basePanelOpen?: boolean,
isLoading?: boolean,
depthTest?: boolean,
},
}
interface CustomFile {
code: string,
name: string,
isVisible: boolean,
urls: string[],
ehrCode: string[],
}
interface EditableCustomFile extends CustomFile {
isDeleting: boolean,
}
interface ToggleableAlert {
code: string,
errorCode: number,
name: string,
isVisible: boolean,
}
Note: The value of these props should not be changed during runtime.
Props can be also passed (optionally) to the <Controls />
elements to set initial behaviour.
Prop | Type | Description | Example |
---|
coords | Cesium.Cartesian3 | undefined | The starting coordinates. | coords={new Cartesian3(3049660.4432725203, 1395285.2320070753, 5407747.336997399)} |
orientation | Cesium.HeadingPitchRoll | undefined | The starting orientation of the camera. | orientation={{ heading: 3.8891689628741344, pitch: -0.5010550170855081, roll: 6.280859574464753 }} |
ehrCode | string | undefined | The application will request for the bounding box of the ehr code from the search api and use this as the starting position. | ehrCode='120836089' |
cadastreCode | string | undefined | The application will request for the bounding box of the cadastre from the search api and use this as the starting position. | cadastreCode='78407:701:0267' |
config | ControlsConfig | undefined | Configuration object for showing the UI buttons, by default everything is shown. | config={{ timeline: { visible: false, }, layers: { visible: true, layers3D: { visible: true, AirzoneLayerButton: { visible: false, }, }, customBuildings: { visible: true, userBuildings: { visible: false, } } } }} |
Full list of controls config object
{
attribution?: {
visible?: boolean,
},
baseLayerButton?: {
visible?: boolean,
},
coordinatesInspector?: {
visible?: boolean,
},
distanceMeasurementButton?: {
visible?: boolean,
},
downloadButton?: {
visible?: boolean,
},
fullscreenButton?: {
visible?: boolean,
},
infoButton?: {
visible?: boolean,
},
locationButton?: {
visible?: boolean,
},
measurement3DButton?: {
visible?: boolean,
},
search?: {
visible?: boolean,
},
terrainTransparencyButton?: {
visible?: boolean,
},
timeline?: {
visible?: boolean,
},
zoomButtons?: {
visible?: boolean,
},
layers?: {
visible?: boolean,
buildings?: {
visible?: boolean,
lod1Buildings?: boolean,
lod2Buildings?: boolean,
lod3Buildings?: boolean,
oldTown?: boolean,
utilities?: boolean,
shadows?: boolean,
},
environment?: {
visible?: boolean,
vegetation?: boolean,
cadastre?: boolean,
},
water?: {
visible?: boolean,
waterSources?: boolean,
hydrants?: boolean,
},
roads?: {
visible?: boolean,
roads?: boolean,
lightRoads?: boolean,
busStops?: boolean,
crossings?: boolean,
exits?: boolean,
bridges?: boolean,
trups?: boolean,
noiseWalls?: boolean,
},
areasAndRestrictions?: {
visible?: boolean,
airZones?: boolean,
kpoWater?: boolean,
kpoEnvironment?: boolean,
kpoTechno?: boolean,
kpoOther?: boolean,
riskAreas?: boolean,
floodMaps?: boolean,
},
information?: {
visible?: boolean,
geology?: boolean,
tileSquares?: boolean,
labels?: boolean,
},
customBuildings?: {
visible?: boolean,
sharedBuildings?: {
visible?: boolean,
},
userBuildings?: {
visible?: boolean,
}
}
}
}
4. Troubleshooting
Text is not showing correctly (e.g. onBoarding.mouseLeft)
The library uses React Intl to configure the showing text.
Inside the messages json that is used on IntlProvider
put the corresponding keys with the translations.
A json with all the keys (+ estonian translations) can be found in node_modules/ehr-3d-twin/etc/sample-intl.json
Invalid hook call. Hooks can only be called inside of the body of a function component.
Check the React
and ReactDOM
versions of ehr-components
(e.g. npm ls react
, npm ls react-dom
).
Make sure you are using those exact versions in your application (in the package.json)
Add a resolution field (for all other libraries that use React
and ReactDOM
to follow)
"resolutions": {
"react": "16.9.0",
"react-dom": "16.9.0"
}
Uncaught Error: [React Intl] Could not find required intl
object. needs to exist in the component ancestry.
Check the ReactIntl
version of ehr-component (e.g.
npm ls react-intl`)
Make sure you are using that exact version in your application (in the package.json)
Add a resolution field
"resolutions": {
"react": "16.9.0",
"react-dom": "16.9.0",
"react-intl": "5.10.16"
},
index.js:1 Error constructing CesiumWidget. Visit http://get.webgl.org to verify that your web browser and hardware support WebGL.
The Cesium library is not imported correctly (see 2. Expose CESIUM_BASE_URL)
Application is not showing correctly / styles are missing
Mta styles are not included in the package, you can include them either on the index.html, on the index.js|ts(x), or on a sass file.
e.g. on a sass file
@import "~ehr-components/build/static/css/mta_visuaal.css"
on index.js
import "../node_modules/ehr-components/build/static/css/mta_visuaal.css";