API (v2.0.0) - Giro3D
    Preparing search index...

    Class Instance

    The instance is the core component of Giro3D. It encapsulates the 3D scene, the current camera and one or more entities. The instance displays the 3D scene in the DOM element specified by the target constructor property.

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

    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(0, 0, 0);

    Hierarchy

    Implements

    Index

    Constructors

    constructor

    Accessors

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

    Methods

    add canvasToNormalizedCoords dispose eventToCanvasCoords eventToNormalizedCoords getEntities getMemoryUsage getObjects normalizedToCanvasCoords notifyChange pickObjectsAt remove

    Constructors

    • Constructs a Giro3D Instance

      Parameters

      • options: InstanceOptions

        Options

        const instance = new Instance({
          target: 'parentElement', // The id of the <div> to attach the instance
          crs: CoordinateSystem.epsg3857,
        });

      Returns Instance

    Accessors

    • get css2DRenderer(): CSS2DRenderer

      Gets the underlying CSS2DRenderer.

      Returns CSS2DRenderer

    • get domElement(): HTMLCanvasElement

      Gets the canvas that this instance renders into.

      Returns HTMLCanvasElement

    • get loading(): boolean

      Gets whether at least one entity is currently loading data.

      Returns boolean

    • 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

    • get renderer(): WebGLRenderer

      Gets the underlying WebGL renderer.

      Returns WebGLRenderer

    • get threeObjects(): Group

      Gets the group containing native Three.js objects.

      Returns Group

    • get viewport(): HTMLDivElement

      Gets the DOM element that contains the Giro3D viewport.

      Returns HTMLDivElement

    Methods

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

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

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

    • 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

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

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

    • 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

      • Optionalfilter: (obj: Entity) => boolean

        the optional filter predicate

      Returns Entity<EntityEventMap, EntityUserData>[]

      an array containing the queried entities

    • 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

      Returns (Object3D<Object3DEventMap> | Entity<EntityEventMap, EntityUserData>)[]

      an array containing the queried objects

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

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

          false
        • OptionalneedsRedraw?: boolean

          Should we render the scene?

          true

      Returns void

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

    Settings

    Member Visibility

    On This Page

    Constructors
    Accessors
    Methods