Constructs a Giro3D Instance
Where to instanciate the Three.js scene in the DOM
Options
const opts = {
crs = exent.crs()
};
const instance = new Instance(viewerDiv, opts);
const map = new Map('myMap', null, extent, { maxSubdivisionLevel: 10 });
instance.add(map);
Gets the currently bound camera controls.
Sets custom camera controls. Prefer Instance.useTHREEControls when possible.
Gets the canvas that this instance renders into.
Gets the rendering engine
Gets whether at least one entity is currently loading data.
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.
Gets the CRS used in this instance.
Gets the underlying WebGL renderer.
Gets the rendering options.
Note: you must call notifyChange() to take the changes into account.
Gets the 3D Scene.
Gets the group containing native Three.js objects.
Gets the DOM element that contains the Giro3D viewport.
Add THREE object or Entity to the instance.
The entity id
must be unique.
the object to add
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('myMap', myMapExtent));
// Add Map to instance then wait for the map to be ready.
instance.add(new Map('myMap', myMapExtent)).then(...);
Dispose of this instance object. Free all memory used.
Note: this will not dispose the following reusable objects:
controls.dispose()
inspector.detach()
Extract canvas coordinates from a mouse-event / touch-event.
event can be a MouseEvent or a TouchEvent
The target to set with the result.
Touch index when using a TouchEvent (default: 0)
canvas coordinates (in pixels, 0-0 = top-left of the instance)
Extract normalized coordinates (NDC) from a mouse-event / touch-event.
event can be a MouseEvent or a TouchEvent
The target to set with the result.
Touch index when using a TouchEvent (default: 0)
NDC coordinates (x and y are [-1, 1])
Moves the camera to look at an object.
Object to look at
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'));
Optional
filter: ((obj) => boolean)the optional filter predicate
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');
Optional
filter: ((obj) => boolean)the optional filter predicate.
an array containing the queried objects
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)
the source(s) of the change. Might be a single object or an array.
Optional
options: { Optional
immediate?: booleanOptional
needsReturn objects from some layers/objects3d under the mouse in this instance.
mouse position in window coordinates, i.e [0, 0] = top-left,
or MouseEvent
or TouchEvent
Options
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({ x, y })
instance.pickObjectsAt({ x, y }, { radius: 1, where: ['wfsBuilding'] })
instance.pickObjectsAt({ x, y }, { radius: 3, where: ['wfsBuilding', myLayer] })
Removes the entity or THREE object from the scene.
the object to remove.
This function allows to use three.js controls (files in examples/{js,jsm}/controls
folder
of THREE.js) into Giro3D 3D scene.
Giro3D supports the controls that check the following assumptions:
update
methodAn instance of a THREE controls
Static
registerCRSRegisters 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(div, { crs: 'EPSG:102115' });
the short name, or EPSG code to identify this CRS.
the CRS definition, either in proj syntax, or in WKT syntax.
The instance is the core component of Giro3D. It encapsulates the 3D scene, the current camera and one or more Entity, such as a Map.