Class Instance

The instance is the core component of Giro3D. It encapsulates the 3D scene, the current camera and one or more entities, such as a Map.

// Create a Giro3D instance in the EPSG:3857 coordinate system:
const instance = new Instance({
    target: 'view',
    crs: 'EPSG:3857',
});

const map = new Map(...);

// Add an entity to the instance
instance.add(map);

// Bind an event listener on double click
instance.domElement.addEventListener('dblclick', () => console.log('double click!'));

// Get the camera position
const position = instance.view.camera.position;

// Set the camera position to be located 10,000 meters above the center of the coordinate system.
instance.view.camera.position.set(0, 0, 10000);
instance.view.camera.lookAt(lookAt);

Hierarchy (view full)

EventDispatcher<InstanceEvents>
- Instance

Implements

Progress

Constructors

constructor

new Instance(options): Instance
Constructs a Giro3D Instance
Parameters
- options: InstanceOptions
  Options
```
const instance = new Instance({
  target: 'parentElement', // The id of the <div> to attach the instance
  crs: 'EPSG:3857',
});
```
Returns Instance
Overrides EventDispatcher.constructor
- Defined in core/Instance.ts:261

Accessors

css2DRenderer

get css2DRenderer(): CSS2DRenderer
Gets the underlying CSS2DRenderer.

Returns CSS2DRenderer
- Defined in core/Instance.ts:431

domElement

get domElement(): HTMLCanvasElement
Gets the canvas that this instance renders into.

Returns HTMLCanvasElement
- Defined in core/Instance.ts:366

engine

get engine(): C3DEngine
Gets the rendering engine

Returns C3DEngine
- Defined in core/Instance.ts:407

loading

get loading(): boolean
Gets whether at least one entity is currently loading data.

Returns boolean
Implementation of Progress.loading
- Defined in core/Instance.ts:381

mainLoop

get mainLoop(): MainLoop
Gets the main loop

Returns MainLoop
- Defined in core/Instance.ts:402

progress

get progress(): number
Gets the progress (between 0 and 1) of the processing of the entire instance. This is the average of the progress values of all entities. Note: This value is only meaningful is loading is true. Note: if no entity is present in the instance, this will always return 1.

Returns number
Implementation of Progress.progress
- Defined in core/Instance.ts:392

referenceCrs

get referenceCrs(): string
Gets the CRS used in this instance.

Returns string
- Defined in core/Instance.ts:376

renderer

get renderer(): WebGLRenderer
Gets the underlying WebGL renderer.

Returns WebGLRenderer
- Defined in core/Instance.ts:424

renderingOptions

get renderingOptions(): RenderingOptions
Gets the rendering options.

Note: you must call notifyChange() to take the changes into account.

Returns RenderingOptions
- Defined in core/Instance.ts:417

scene

get scene(): Scene
Gets the 3D Scene.

Returns Scene
- Defined in core/Instance.ts:436

threeObjects

get threeObjects(): Group<Object3DEventMap>
Gets the group containing native Three.js objects.

Returns Group<Object3DEventMap>
- Defined in core/Instance.ts:441

view

get view(): renderer.View
Gets the view.

Returns renderer.View
- Defined in core/Instance.ts:446

viewport

get viewport(): HTMLDivElement
Gets the DOM element that contains the Giro3D viewport.

Returns HTMLDivElement
- Defined in core/Instance.ts:371

Methods

add

add<T>(object): Promise<T>
Add THREE object or Entity to the instance. The entity id must be unique.
Type Parameters
- T extends Object3D<Object3DEventMap> | Entity<EntityEventMap, EntityUserData>
Parameters
- object: T
  the object to add
Returns Promise<T>
a promise resolved with the new layer object when it is fully initialized or rejected if any error occurred.
Example
```
// Add Map to instance
instance.add(new Map(...);

// Add Map to instance then wait for the map to be ready.
instance.add(new Map(...).then(...);
```
- Defined in core/Instance.ts:513

addEventListener

addEventListener<T>(type, listener): void
Adds a listener to an event type.
Type Parameters
- T extends keyof InstanceEvents
Parameters
- type: T
  The type of event to listen to.
- listener: EventListener<InstanceEvents[T], T, Instance>
  The function that gets called when the event is fired.
Returns void
Inherited from EventDispatcher.addEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:52
addEventListener<T>(type, listener): void
Type Parameters
- T extends string
Parameters
- type: T
- listener: EventListener<{}, T, Instance>
Returns void
Inherited from EventDispatcher.addEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:56

canvasToNormalizedCoords

canvasToNormalizedCoords(canvasCoords, target): Vector2
Convert canvas coordinates to normalized device coordinates (NDC).
Parameters
- canvasCoords: Vector2
  (in pixels, 0-0 = top-left of the instance)
- target: Vector2
  The target to set with the result.
Returns Vector2
NDC coordinates (x and y are [-1, 1])
- Defined in core/Instance.ts:777

dispatchEvent

dispatchEvent<T>(event): void
Fire an event type.
Type Parameters
- T extends keyof InstanceEvents
Parameters
- event: BaseEvent<T> & InstanceEvents[T]
  The event that gets fired.
Returns void
Inherited from EventDispatcher.dispatchEvent
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:84

dispose

dispose(): void
Dispose of this instance object. Free all memory used.

Note: this will not dispose the following reusable objects:
- controls (because they can be attached and detached). For THREE.js controls, use controls.dispose()
- Inspectors, use inspector.detach()
- any openlayers objects, please see their individual documentation
Returns void
- Defined in core/Instance.ts:479

eventToCanvasCoords

eventToCanvasCoords(event, target, touchIdx?): Vector2
Extract canvas coordinates from a mouse-event / touch-event.
Parameters
- event: MouseEvent | TouchEvent
  event can be a MouseEvent or a TouchEvent
- target: Vector2
  The target to set with the result.
- touchIdx: number = 0
  Touch index when using a TouchEvent (default: 0)
Returns Vector2
canvas coordinates (in pixels, 0-0 = top-left of the instance)
- Defined in core/Instance.ts:730

eventToNormalizedCoords

eventToNormalizedCoords(event, target, touchIdx?): Vector2
Extract normalized coordinates (NDC) from a mouse-event / touch-event.
Parameters
- event: MouseEvent | TouchEvent
  event can be a MouseEvent or a TouchEvent
- target: Vector2
  The target to set with the result.
- touchIdx: number = 0
  Touch index when using a TouchEvent (default: 0)
Returns Vector2
NDC coordinates (x and y are [-1, 1])
- Defined in core/Instance.ts:759

focusObject

focusObject(obj): void
Moves the camera to look at an object.
Parameters
- obj: Object3D<Object3DEventMap> | Entity3D<Entity3DEventMap, EntityUserData>
  Object to look at
Returns void
- Defined in core/Instance.ts:911

getEntities

getEntities(filter?): Entity<EntityEventMap, EntityUserData>[]
Get all entities, with an optional predicate applied.
```
// get all entities
const allEntities = instance.getEntities();

// get all entities whose name contains 'building'
const buildings = instance.getEntities(entity => entity.name.includes('building'));
```
Parameters
- Optional filter: ((obj) => boolean)
  the optional filter predicate
  - - (obj): boolean
    - Parameters
      obj: Entity<EntityEventMap, EntityUserData>
      Returns boolean
Returns Entity<EntityEventMap, EntityUserData>[]
an array containing the queried entities
- Defined in core/Instance.ts:700

getMemoryUsage

getMemoryUsage(): MemoryUsageReport
Returns MemoryUsageReport
- Defined in core/Instance.ts:939

getObjects

getObjects(filter?): (Object3D<Object3DEventMap> | Entity<EntityEventMap, EntityUserData>)[]
Get all top-level objects (entities and regular THREE objects), using an optional filter predicate.
```
// get all objects
const allObjects = instance.getObjects();
// get all object whose name includes 'foo'
const fooObjects = instance.getObjects(obj => obj.name === 'foo');
```
Parameters
- Optional filter: ((obj) => boolean)
  the optional filter predicate.
  - - (obj): boolean
    - Parameters
      obj: Object3D<Object3DEventMap> | Entity<EntityEventMap, EntityUserData>
      Returns boolean
Returns (Object3D<Object3DEventMap> | Entity<EntityEventMap, EntityUserData>)[]
an array containing the queried objects
- Defined in core/Instance.ts:672

hasEventListener

hasEventListener<T>(type, listener): boolean
Checks if listener is added to an event type.
Type Parameters
- T extends keyof InstanceEvents
Parameters
- type: T
  The type of event to listen to.
- listener: EventListener<InstanceEvents[T], T, Instance>
  The function that gets called when the event is fired.
Returns boolean
Inherited from EventDispatcher.hasEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:63
hasEventListener<T>(type, listener): boolean
Type Parameters
- T extends string
Parameters
- type: T
- listener: EventListener<{}, T, Instance>
Returns boolean
Inherited from EventDispatcher.hasEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:67

normalizedToCanvasCoords

normalizedToCanvasCoords(ndcCoords, target): Vector2
Convert NDC coordinates to canvas coordinates.
Parameters
- ndcCoords: Vector2
  The NDC coordinates to convert
- target: Vector2
  The target to set with the result.
Returns Vector2
canvas coordinates (in pixels, 0-0 = top-left of the instance)
- Defined in core/Instance.ts:790

notifyChange

notifyChange(changeSources?, options?): void
Notifies the scene it needs to be updated due to changes exterior to the scene itself (e.g. camera movement). non-interactive events (e.g: texture loaded)
Parameters
- changeSources: unknown = undefined
  The source(s) of the change. Might be a single object or an array.
- Optional options: {
  immediate?: boolean;
  needsRedraw?: boolean;
  }
  Notification options.
  - Optional immediate?: boolean
    Should the update be immediate? If false, the update is deferred to the next animation frame.
    Default Value
    false
  - Optional needsRedraw?: boolean
    Should we render the scene?
    Default Value
    true
Returns void
- Defined in core/Instance.ts:593

pickObjectsAt

pickObjectsAt(mouseOrEvt, options?): PickResult<unknown>[]
Return objects from some layers/objects3d under the mouse in this instance.
Parameters
- mouseOrEvt: Vector2 | MouseEvent | TouchEvent
  mouse position in window coordinates, i.e [0, 0] = top-left, or MouseEvent or TouchEvent
- options: PickObjectsAtOptions = {}
  Options
Returns PickResult<unknown>[]
An array of objects. Each element contains at least an object property which is the Object3D under the cursor. Then depending on the queried layer/source, there may be additionnal properties (coming from THREE.Raycaster for instance). If options.pickFeatures if true, features property may be set.
```
instance.pickObjectsAt(mouseEvent)
instance.pickObjectsAt(mouseEvent, { radius: 1, where: [entity0, entity1] })
instance.pickObjectsAt(mouseEvent, { radius: 3, where: [entity0] })
```
- Defined in core/Instance.ts:829

remove

remove(object): void
Removes the entity or THREE object from the scene.
Parameters
- object: Object3D<Object3DEventMap> | Entity<EntityEventMap, EntityUserData>
  the object to remove.
Returns void
- Defined in core/Instance.ts:563

removeEventListener

removeEventListener<T>(type, listener): void
Removes a listener from an event type.
Type Parameters
- T extends keyof InstanceEvents
Parameters
- type: T
  The type of the listener that gets removed.
- listener: EventListener<InstanceEvents[T], T, Instance>
  The listener function that gets removed.
Returns void
Inherited from EventDispatcher.removeEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:74
removeEventListener<T>(type, listener): void
Type Parameters
- T extends string
Parameters
- type: T
- listener: EventListener<{}, T, Instance>
Returns void
Inherited from EventDispatcher.removeEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:78

`Static` registerCRS

registerCRS(name, value): void
Registers a new coordinate reference system. This should be done before creating the instance. This method can be called several times to add multiple CRS.
```
 // register the CRS first...
 Instance.registerCRS(
 'EPSG:102115',
 '+proj=utm +zone=5 +ellps=clrk66 +units=m +no_defs +type=crs');

 // ...then create the instance
 const instance = new Instance({ crs: 'EPSG:102115' });
```
Parameters
- name: string
  the short name, or EPSG code to identify this CRS.
- value: string
  the CRS definition, either in proj syntax, or in WKT syntax.
Returns void
- Defined in core/Instance.ts:629

Class Instance

Hierarchy (view full)

Implements

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns Instance

Accessors

css2DRenderer

Returns CSS2DRenderer

domElement

Returns HTMLCanvasElement

engine

Returns C3DEngine

loading

Returns boolean

mainLoop

Returns MainLoop

progress

Returns number

referenceCrs

Returns string

renderer

Returns WebGLRenderer

renderingOptions

Returns RenderingOptions

scene

Returns Scene

threeObjects

Returns Group<Object3DEventMap>

view

Returns renderer.View

viewport

Returns HTMLDivElement

Methods

add

Type Parameters

Parameters

Returns Promise<T>

Example

addEventListener

Type Parameters

Parameters

Returns void

Type Parameters

Parameters

Returns void

canvasToNormalizedCoords

Parameters

Returns Vector2

dispatchEvent

Type Parameters

Parameters

Returns void

dispose

Returns void

eventToCanvasCoords

Parameters

Returns Vector2

eventToNormalizedCoords

Parameters

Returns Vector2

focusObject

Parameters

Returns void

getEntities

Parameters

Parameters

Returns boolean

Returns Entity<EntityEventMap, EntityUserData>[]

getMemoryUsage

Returns MemoryUsageReport

getObjects

Parameters

Parameters

Returns boolean

`Optional` immediate?: boolean

`Optional` needsRedraw?: boolean

`Static` registerCRS