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)

Implements

Constructors

constructor

Accessors

css2DRenderer domElement engine loading mainLoop progress referenceCrs renderer renderingOptions scene threeObjects view viewport

Methods

add addEventListener canvasToNormalizedCoords dispatchEvent dispose eventToCanvasCoords eventToNormalizedCoords focusObject getEntities getMemoryUsage getObjects hasEventListener normalizedToCanvasCoords notifyChange pickObjectsAt remove removeEventListener registerCRS

Constructors

constructor

Accessors

css2DRenderer

  • get css2DRenderer(): CSS2DRenderer

  • Gets the underlying CSS2DRenderer.

    Returns CSS2DRenderer

domElement

  • get domElement(): HTMLCanvasElement

  • Gets the canvas that this instance renders into.

    Returns HTMLCanvasElement

engine

loading

  • get loading(): boolean

  • Gets whether at least one entity is currently loading data.

    Returns boolean

mainLoop

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

referenceCrs

  • get referenceCrs(): string

  • Gets the CRS used in this instance.

    Returns string

renderer

renderingOptions

scene

threeObjects

view

viewport

  • get viewport(): HTMLDivElement

  • Gets the DOM element that contains the Giro3D viewport.

    Returns HTMLDivElement

Methods

add

  • add<T>(object): Promise<T>

  • Add THREE object or Entity to the instance.

    If the object or entity has no parent, it will be added to the default tree (i.e under .scene for entities and under .threeObjects for regular Object3Ds.).

    If the object or entity already has a parent, then it will not be changed. Check that this parent is present in the scene graph (i.e has the .scene object as ancestor), otherwise it will never be displayed.

    Type Parameters

    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(...);

addEventListener

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])

dispatchEvent

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

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)

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])

focusObject

getEntities

getMemoryUsage

getObjects

hasEventListener

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)

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.

    • Optionaloptions: {
          immediate?: boolean;
          needsRedraw?: boolean;
      }

      Notification options.

      • Optionalimmediate?: boolean

        Should the update be immediate? If false, the update is deferred to the next animation frame.

        Default Value

        false
      • OptionalneedsRedraw?: boolean

        Should we render the scene?

        Default Value

        true

    Returns void

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] })

remove

removeEventListener

StaticregisterCRS

  • 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

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods