EHR 3D Twin library component

The 3D Map of Estonia.

Prerequisites

npm 18.19.1

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 and can't be deployed independetly, thus the following libraries must also be present:

• "ehr-components": "0.2.17"
• "react-intl": "5.25.1"
• "axios": "0.21.0"
• "ehr-auth-react": "0.0.38"
• "keycloak-js": "11.0.2"

Quickstart

All previous dependencies can be installed (e.g. on a fresh project) using yarn add react react-dom ehr-components react-intl axios ehr-auth-react keycloak-js, but check after installation correct versions in package.json file.

Installation

1. Install the ehr-3d-twin dependencie

yarn add ehr-3d-twin

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.95/Build/Cesium/Cesium.js"></script>
<link href="https://cesium.com/downloads/cesiumjs/releases/1.95/Build/Cesium/Widgets/widgets.css" rel="stylesheet">

Easy way (Craco)

Extend the configuration for react-scripts to serve cesium for you.

1. Install Craco yarn add @craco/craco craco-cesium

2. Change scripts in package.json

     "scripts": {
         "start": "craco start",
         "build": "craco build",
         "test": "craco test",
         "eject": "react-scripts eject"
     },

3. Create the Craco configuration file in the root of the project craco.config.js

4. Extend the Cesium configuration, add this code inside the file:

     module.exports = {
       plugins: [
         {
           plugin: require("craco-cesium")()
         }
       ]
     };

More information on this method

• Craco-cesium

Statically serve the cesium built files with custom bundler

1. 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

2. Configure the application bundler to serve these files
3. 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
4. Import cesium into the project

     import * as Cesium from 'cesium';
     import "cesium/Build/Cesium/Widgets/widgets.css";

More information on this method

• Cesium quickstart
• Cesium and webpack

3. Add translations

1. Make lang folder in the root of the project
2. Copy et-EE.json file to lang folder

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.

on index.js

  import "../node_modules/ehr-components/build/static/css/mta_visuaal.css";

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: 'https://livekluster.ehr.ee',APP_1: 'https://livekluster.ehr.ee',APP_2: 'https://livekluster.ehr.ee',APP_3: 'https://livekluster.ehr.ee',APP_4: 'https://livekluster.ehr.ee',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',MAAMET_KATASTER: 'https://ky.kataster.ee',KINNISTUSRAAMAT: 'https://kinnistusraamat.rik.ee',GSAVALIK: 'https://gsavalik.envir.ee',TALLINN: 'https://gis.tallinn.ee/veebikaart/',DOCUMENT_SERVICE_ENDPOINT: 'https://livekluster.ehr.ee/api/document/v1',CLASSIFIER_SERVICE_ENDPOINT: 'https://livekluster.ehr.ee/api/classifier/v1',PLANK: 'https://planeeringud.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,
        },
        showRoadsETAK?: {
          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,
        },
        showTrees?: boolean,
        showForests?: 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,
          MAAMET_KATASTER: string,
          KINNISTUSRAAMAT: string,
          GSAVALIK: string,
          TALLINN: string,
          PLANK: string,
		  DOCUMENT_SERVICE_ENDPOINT: string,
		  CLASSIFIER_SERVICE_ENDPOINT: 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,
      }
    },

    modellingTool?: {
      visible?: boolean,
    },

    thirdPartyLayers?: {
      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": "18.2.0",
    "react-dom": "18.2.0"
  }

Error: Cannot find module 'eslint-visitor-keys

Add a resolution field

  "resolutions": {
  	"eslint": "7.28.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": "18.2.0",
    "react-dom": "18.2.0",
    "react-intl": "5.25.1"
  },

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";

Application is not responding

Make sure you are not using React.StrictMode