1.0.0
Controls the camera of a xeometry.Viewer with the mouse.
This is xeometry's bundled, default camera control.
(Viewer)
A Viewer.
(Object?)
Configs
var viewer = new xeometry.Viewer();
var cameraControl = new xeometry.CameraControl(viewer);
A JavaScript API for viewing glTF models on WebGL.
A xeometry Viewer is a single class that wraps xeogl in a set of simple data-driven methods focused on loading glTF models and manipulating their objects to create cool presentations.
// Create viewer with default canvas
var viewer1 = new xeometry.Viewer();
// Create viewer bound to an existing canvas
var viewer2 = new xeometry.Viewer({
canvas: "theCanvas"
});
// Create viewer that loads via custom loader callback
var viewer3 = new xeometry.Viewer({
loadModel: function (modelId, src, ok, error) {
var request = new XMLHttpRequest();
request.overrideMimeType("application/json");
request.open('GET', src2, true);
request.onreadystatechange = function () {
if (request.readyState == 4 && // Request finished, response ready
request.status == "200") { // Status OK
var json = JSON.parse(request.responseText);
ok(json, this);
}
};
request.send(null);
},
loadedModel: function(modelId, src, ok) {
console.log("Loaded modelId=" + modelId);
ok(); // Unblock the viewer
},
unloadedModel: function(modelId, src) {
console.log("Unloaded modelId=" + modelId);
}
});
Schedules a task for the viewer to run asynchronously at the next opportunity.
Internally, this pushes the task to a FIFO queue. Within each frame interval, the viewer pumps the queue for a certain period of time, popping tasks and running them. After each frame interval, tasks that did not get a chance to run during the task are left in the queue to be run next time.
Viewer
:
this
viewer.scheduleTask(function() { ... });
viewer.scheduleTask(function() { this.log("foo"); }, console); // Set a scope for the task
Gets the viewer's WebGL canvas.
HTMLCanvasElement
:
Returns the HTML DIV element that overlays the WebGL canvas.
This overlay is for catching mouse navigation events.
HTMLDivElement
:
Loads a model into the viewer.
Assigns the model an ID, which gets prefixed to the IDs of its objects.
(String)
ID to assign to the model. This gets prefixed to the IDs of the model's objects.
(String)
Locates the model. This could be a path to a file or an ID within a database.
(Function?)
Callback fired when model loaded.
Viewer
:
this
// Load saw model, fit in view, show two of its objects
viewer.loadModel("saw", "models/gltf/ReciprocatingSaw/glTF-MaterialsCommon/ReciprocatingSaw.gltf", function () {
viewer.viewFit("saw");
viewer.hide();
viewer.show(["saw#0.1", "saw#0.2"]);
});
Gets the source of a model.
This is the src
parameter that was given to #loadModel.
(String)
ID of the model.
String
:
Model source.
Gets the objects belonging to the given models and/or types.
Returns all objects in the viewer when no arguments are given.
Array<String>
:
IDs of the objects.
// Get all objects currently in the viewer
var allObjects = viewer.getObjects();
// Get all objects in the gearbox model
var gearboxObjects = viewer.getObjects("gearbox");
// Get objects belonging to two models
var sawAndGearboxObjects = viewer.getObjects(["saw", "gearbox"]);
// Get objects in the gearbox model, plus all objects in viewer that are IFC cable fittings and carriers
var gearboxCableFittings = viewer.getObjects("gearbox", "IfcCableFitting", "IfcCableCarrierFitting"]);
Unloads all models, annotations and clipping planes, resets lights to defaults.
Preserves the current camera state.
Viewer
:
this
Gets an object's geometry primitive type.
This determines the layout of the indices array of the object's geometry.
(String)
ID of the object.
String
:
The primitive type. Possible values are 'points', 'lines', 'line-loop',
'line-strip', 'triangles', 'triangle-strip' and 'triangle-fan'.
var prim = viewer.getPrimitive("saw#3.1");
Gets the World-space geometry vertex positions of an object.
(String)
ID of the object.
Float32Array
:
The vertex positions.
var positions = viewer.getPositions("saw#3.1");
Gets the geometry primitive indices of an object.
(String)
ID of the object.
Int32Array
:
The indices.
var indices = viewer.getIndices("saw#3.1");
Sets the scale of a model or an object.
An object's scale is relative to its model's scale. For example, if an object has a scale
of [0.5, 0.5, 0.5]
and its model also has scale [0.5, 0.5, 0.5]
, then the object's
effective scale is [0.25, 0.25, 0.25]
.
A model or object's scale is [1.0, 1.0, 1.0]
by default.
(String)
ID of a model or object.
Viewer
:
this
viewer.setScale("saw", [1.5, 1.5, 1.5]);
viewer.setScale("saw#3.1", [0.5, 0.5, 0.5]);
Gets the scale of a model or an object.
An object's scale is relative to its model's scale. For example, if an object has a scale
of [0.5, 0.5, 0.5]
and its model also has scale [0.5, 0.5, 0.5]
, then the object's
effective scale is [0.25, 0.25, 0.25]
.
A model or object's scale is [1.0, 1.0, 1.0]
by default.
(String)
ID of a model or object.
[Number, Number, Number]
:
Scale factors for the X, Y and Z axis.
var sawScale = viewer.getScale("saw");
var sawCoverScale = viewer.getScale("saw#3.1");
Sets the rotation of a model or an object.
An object's rotation is relative to its model's rotation. For example, if an object has a rotation
of 45
degrees about the Y axis, and its model also has a rotation of 45
degrees about
Y, then the object's effective rotation is 90
degrees about Y.
Rotations are in order of X, Y then Z.
The rotation angles of each model or object are [0, 0, 0]
by default.
(String)
ID of a model or object.
Viewer
:
this
viewer.setRotate("saw", [90, 0, 0]);
viewer.setRotate("saw#3.1", [0, 35, 0]);
Gets the rotation of a model or an object.
An object's rotation is relative to its model's rotation. For example, if an object has a rotation
of 45
degrees about the Y axis, and its model also has a rotation of 45
degrees about
Y, then the object's effective rotation is 90
degrees about Y.
The rotation angles of each model or object are [0, 0, 0]
by default.
Rotations are in order of X, Y then Z.
(String)
ID of a model or object.
[Number, Number, Number]
:
Rotation angles, in degrees, for the X, Y and Z axis.
var sawRotate = viewer.getRotate("saw");
var sawCoverRotate = viewer.getRotate("saw#3.1");
Sets the translation of a model or an object.
An object's translation is relative to that of its model. For example, if an object has a translation
of [100, 0, 0]
and its model has a translation of [50, 50, 50]
, then the object's effective
translation is [150, 50, 50]
.
The translation of each model or object is [0, 0, 0]
by default.
Viewer
:
this
viewer.setTranslate("saw", [100, 30, 0]);
viewer.setTranslate("saw#3.1", [50, 30, 0]);
Increments or decrements the translation of a model or an object.
Viewer
:
this
viewer.addTranslate("saw", [10,0,0]);
viewer.addTranslate("saw#3.1", [10,0,0]);
Gets the translation of a model or an object.
An object's translation is relative to that of its model. For example, if an object has a translation
of [100, 0, 0]
and its model has a translation of [50, 50, 50]
, then the object's effective
translation is [150, 50, 50]
.
The translation of each model or object is [0, 0, 0]
by default.
(String)
ID of a model or an object.
[Number, Number, Number]
:
World-space translation vector.
var sawTranslate = viewer.getTranslate("saw");
var sawCoverTranslate = viewer.getTranslate("saw#3.1");
Shows model/object/types/clip/annotation/light(s).
Shows all objects in the viewer when no arguments are given.
Objects are visible by default.
Viewer
:
this
// Show all objects in the viewer
viewer.show();
// Show all objects in models "saw" and "gearbox"
viewer.show(["saw", "gearbox"]);
// Show two objects in model "saw", plus all objects in model "gearbox"
viewer.show(["saw#0.1", "saw#0.2", "gearbox"]);
// Show objects in the model "gearbox", plus all objects in viewer that are IFC cable fittings and carriers
viewer.show("gearbox", "IfcCableFitting", "IfcCableCarrierFitting"]);
Hides model/object/types/clip/annotation/light(s).
Hides all objects in the viewer when no arguments are given.
Objects are visible by default.
Viewer
:
this
// Hide all objects in the viewer
viewer.hide();
// Hide all objects in models "saw" and "gearbox"
viewer.hide(["saw", "gearbox"]);
// Hide two objects in model "saw", plus all objects in model "gearbox"
viewer.hide(["saw#0.1", "saw#0.2", "gearbox"]);
// Hide objects in the model "gearbox", plus all objects in viewer that are IFC cable fittings and carriers
viewer.hide("gearbox", "IfcCableFitting", "IfcCableCarrierFitting"]);
Sets the opacity of model/object/type(s).
Viewer
:
this
// Create an X-ray view of two objects in the "saw" model
viewer.setOpacity("saw", 0.4);
viewer.setOpacity(["saw#0.1", "saw#0.2"], 1.0);
Sets the color of model/object/type/light(s).
Viewer
:
this
// Set all objects in saw model red
viewer.setColor("saw", [1,0,0]);
// Set two objects in saw model green
viewer.setColor(["saw#0.1", "saw#0.2"], [0,1,0]);
Makes model/object/type(s) clippable.
Makes all objects in the viewer clippable when no arguments are given.
Objects are clippable by default.
Viewer
:
this
// Make all objects in the viewer clippable
viewer.setClippable();
// Make all objects in models "saw" and "gearbox" clippable
viewer.setClippable(["saw", "gearbox"]);
// Make two objects in model "saw" clippable, plus all objects in model "gearbox"
viewer.setClippable(["saw#0.1", "saw#0.2", "gearbox"]);
// Make objects in the model "gearbox" clippable, plus all objects in viewer that are IFC cable fittings and carriers
viewer.setClippable("gearbox", "IfcCableFitting", "IfcCableCarrierFitting"]);
Makes model/object/type(s) unclippable.
Unclippable objects will then remain fully visible when they would otherwise be clipped by clipping planes.
Makes all objects in the viewer unclippable when no arguments are given.
Objects are clippable by default.
Viewer
:
this
// Make all objects in the viewer unclippable
viewer.setUnclippable();
// Make all objects in models "saw" and "gearbox" unclippable
viewer.setUnclippable(["saw", "gearbox"]);
// Make two objects in model "saw" unclippable, plus all objects in model "gearbox"
viewer.setUnclippable(["saw#0.1", "saw#0.2", "gearbox"]);
// Make all objects in the model "gearbox" unclippable, plus all objects in viewer that are IFC cable fittings and carriers
viewer.setUnclippable("gearbox", "IfcCableFitting", "IfcCableCarrierFitting"]);
Shows outline around model/object/type(s).
Outlines all objects in the viewer when no arguments are given.
Viewer
:
this
viewer.showOutline(); // Show outline around all objects in viewer
viewer.showOutline("saw"); // Show outline around all objects in saw model
viewer.showOutline(["saw#0.1", "saw#0.2"]); // Show outline around two objects in saw model
Hides outline around model/object/type(s).
Hides all outlines in the viewer when no arguments are given.
Viewer
:
this
viewer.hideOutline(); // Hide outline around all objects in viewer
viewer.hideOutline("saw"); // Hide outline around all objects in saw model
viewer.hideOutline(["saw#0.1", "saw#0.2"]); // Hide outline around two objects in saw model
Gets the World-space center point of the given given model/object/types/clip/annotation/light(s).
When no arguments are given, returns the collective center of all objects in the viewer.
[Number, Number, Number]
:
The World-space center point.
viewer.getCenter(); // Gets collective center of all objects in the viewer
viewer.getCenter("saw"); // Gets collective center of all objects in saw model
viewer.getCenter(["saw", "gearbox"]); // Gets collective center of all objects in saw and gearbox models
viewer.getCenter("saw#0.1"); // Get center of an object in the saw model
viewer.getCenter(["saw#0.1", "saw#0.2"]); // Get collective center of two objects in saw model
Gets the axis-aligned World-space boundary of the given model/object/type/annotation/light(s).
When no arguments are given, returns the collective boundary of all objects in the viewer.
[Number, Number, Number, Number, Number, Number]
:
An axis-aligned World-space bounding box, given as elements
[xmin, ymin, zmin, xmax, ymax, zmax]
.
viewer.getAABB(); // Gets collective boundary of all objects in the viewer
viewer.getAABB("saw"); // Gets collective boundary of all objects in saw model
viewer.getAABB(["saw", "gearbox"]); // Gets collective boundary of all objects in saw and gearbox models
viewer.getAABB("saw#0.1"); // Get boundary of an object in the saw model
viewer.getAABB(["saw#0.1", "saw#0.2"]); // Get collective boundary of two objects in saw model
Locks the camera's vertical rotation axis to the World-space Y axis.
Viewer
:
this
Allows camera yaw rotation around the camera's "up" vector.
Viewer
:
this
Sets the camera's flight duration when fitting elements to view.
Initial default value is 0.5
seconds.
A value of zero (default) will cause the camera to instantly jump to each new target .
(Number)
The new flight duration, in seconds.
Viewer
:
this
Sets the target field-of-view (FOV) angle when fitting elements to view.
This is the portion of the total frustum FOV that the elements' boundary will occupy when fitted to view.
Default value is 45.
(Number)
The new view-fit FOV angle, in degrees.
Viewer
:
this
Moves the camera to fit the given model/object/annotation/light/boundary(s).
Preserves the direction that the camera is currently pointing in.
A boundary is an axis-aligned World-space bounding box, given as elements [xmin, ymin, zmin, xmax, ymax, zmax]
.
((String | []))
The elements to fit in view, given as either the ID of an annotation, model or object, a boundary, or an array containing mixture of IDs and boundaries.
(Function?)
Callback fired when camera has arrived at its target position.
Viewer
:
this
Moves the camera to fit the given model/object/annotation/light/boundary(s) in view, while looking along the +X axis.
((String | []))
The element(s) to fit in view, given as either the ID of model, ID of object, a boundary, or an array containing mixture of IDs and boundaries.
(Function?)
Callback fired when camera has arrived at its target position.
Viewer
:
this
Moves the camera to fit the given model/object/annotation/light/boundary(s) in view, while looking along the +Z axis.
((String | []))
The element(s) to fit in view, given as either the ID of model, ID of object, a boundary, or an array containing mixture of IDs and boundaries.
(Function?)
Callback fired when camera has arrived at its target position.
Viewer
:
this
Moves the camera to fit the given model/object/annotation/light/boundary(s) in view, while looking along the -X axis.
((String | []))
The element(s) to fit in view, given as either the ID of model, ID of object, a boundary, or an array containing mixture of IDs and boundaries.
(Function?)
Callback fired when camera has arrived at its target position.
Viewer
:
this
Moves the camera to fit the given model/object/annotation/light/boundary(s) in view, while looking along the +X axis.
((String | []))
The element(s) to fit in view, given as either the ID of model, ID of object, a boundary, or an array containing mixture of IDs and boundaries.
(Function?)
Callback fired when camera has arrived at its target position.
Viewer
:
this
Moves the camera to fit the given model/object/annotation/light/boundary(s) in view, while looking along the -Y axis.
((String | []))
The element(s) to fit in view, given as either the ID of model, ID of object, a boundary, or an array containing mixture of IDs and boundaries.
(Function?)
Callback fired when camera has arrived at its target position.
Viewer
:
this
Moves the camera to fit the given model/object/annotation/light/boundary(s) in view, while looking along the +X axis.
((String | []))
The element(s) to fit in view, given as either the ID of model, ID of object, a boundary, or an array containing mixture of IDs and boundaries.
(Function?)
Callback fired when camera has arrived at its target position.
Viewer
:
this
Picks the first object that intersects the given ray.
{id: String}
:
If object found, a hit record containing the ID of the object, else null.
var hit = viewer.rayCastObject([0,0,-5], [0,0,1]);
if (hit) {
var objectId = hit.id;
}
Picks the first object that intersects the given ray, along with geometric information about the ray-object intersection.
{id: String, worldPos: [number, number, number], primIndex: number, bary: [number, number, number]}
:
If object
found, a hit record containing the ID of object, World-space 3D surface intersection, primitive index and
barycentric coordinates, else null.
var hit = viewer.rayCastSurface([0,0,-5], [0,0,1]);
if (hit) {
var objectId = hit.id;
var primitive = hit.primitive;
var primIndex = hit.primIndex;
var bary = hit.bary;
}
Picks the closest object behind the given canvas coordinates.
This is equivalent to firing a ray through the canvas, down the negative Z-axis, to find the first entity it hits.
{id: String}
:
If object found, a hit record containing the ID of the object, else null.
var hit = viewer.pickObject([234, 567]);
if (hit) {
var objectId = hit.id;
}
Picks the closest object behind the given canvas coordinates, along with geometric information about the point on the object's surface that lies right behind those canvas coordinates.
{id: String, worldPos: [number, number, number], primIndex: number, bary: [number, number, number]}
:
If object
found, a hit record containing the ID of object, World-space 3D surface intersection, primitive index and
barycentric coordinates, else null.
var hit = viewer.pickSurface([234, 567]);
if (hit) {
var objectId = hit.id;
var primitive = hit.primitive;
var primIndex = hit.primIndex;
var bary = hit.bary;
}
Creates an annotation.
An annotation is a labeled pin that's attached to the surface of an object.
An annotation is pinned within a triangle of an object's geometry, at a position given in barycentric
coordinates. A barycentric coordinate is a three-element vector that indicates the position within
the triangle as a weight per vertex, where a value of [0.3,0.3,0.3]
places the annotation
at the center of its triangle.
An annotation can be configured with an optional camera position from which to view it, given as eye
,
look
and up
vectors.
By default, an annotation will be invisible while occluded by other objects in the 3D view.
Note that when you pick an object with #.Viewer#rayCastSurface or #.Viewer#pickSurface, you'll get a triangle index and barycentric coordinates in the intersection result. This makes it convenient to create annotations directly from pick results.
(String)
ID for the new annotation.
(Object)
Properties for the new annotation.
Name | Description |
---|---|
cfg.object String
|
ID of an object to pin the annotation to. |
cfg.glyph String?
(default "" )
|
A glyph for the new annotation. This appears in the annotation's pin and is typically a short string of 1-2 chars, eg. "a1". |
cfg.title String?
(default "" )
|
Title text for the new annotation. |
cfg.desc String?
(default "" )
|
Description text for the new annotation. |
cfg.primIndex Number
|
Index of a triangle, within the object's geometry indices, to attach the annotation to. |
cfg.bary [Number, Number, Number]
|
Barycentric coordinates within the triangle, at which to position the annotation. |
cfg.eye [Number, Number, Number]?
|
Eye position for optional camera viewpoint. |
cfg.look [Number, Number, Number]?
|
Look position for optional camera viewpoint. |
cfg.up [Number, Number, Number]?
|
Up direction for optional camera viewpoint. |
cfg.occludable Boolean?
(default true )
|
Whether or not the annotation dissappears while occluded by something else in the 3D view. |
cfg.pinShown Boolean?
(default true )
|
Whether or not the annotation's pin is initially shown. |
cfg.labelShown Boolean?
(default true )
|
Whether or not the annotation's label is initially shown. |
Viewer
:
this
Destroys all annotations.
Viewer
:
This viewer
Sets the triangle that an annotation is pinned to.
The triangle is indicated by the position of the first of the triangle's vertex indices within the object's geometry indices array.
(String)
ID of the annotation.
(Number)
The index of the triangle's first element within the geometry's
indices array.
Viewer
:
This viewer
Gets the triangle that an annotation is pinned to.
The triangle is indicated by the position of the first of the triangle's vertex indices within the object's geometry indices array.
(String)
ID of the annotation.
Number
:
The index of the triangle's first element within the geometry's indices array.
Sets the barycentric coordinates of an annotation within its triangle.
A barycentric coordinate is a three-element vector that indicates the position within the triangle as a weight per vertex,
where a value of [0.3,0.3,0.3]
places the annotation at the center of its triangle.
Viewer
:
This
Creates a user-defined clipping plane.
The plane is positioned at a given World-space position and oriented in a given direction.
(String)
Unique ID to assign to the clipping plane.
(Object)
Clip plane configuration.
Name | Description |
---|---|
cfg.pos [Number, Number, Number]?
(default 0,0,0 )
|
World-space position of the clip plane. |
cfg.dir [Number, Number, Number]?
(default 0,0,-1 )
|
Vector indicating the orientation of the clip plane. |
cfg.active Boolean?
(default true )
|
Whether the clip plane is initially active. Only clips while this is true. |
cfg.shown Boolean?
(default true )
|
Whether to show a helper object to indicate the clip plane's position and orientation.
the front of the plane (with respect to the plane orientation vector), while
-1
discards elements behind the plane.
|
Viewer
:
this
Removes all clip planes from this viewer.
Viewer
:
this
Creates a light source.
(String)
Unique ID to assign to the lightping plane.
(Object)
Light plane configuration.
Name | Description |
---|---|
cfg.pos [Number, Number, Number]?
(default 0,0,0 )
|
World-space position of the light plane. |
cfg.shown Boolean?
(default true )
|
Whether to show a helper object to indicate the light plane's position and orientation.
the front of the plane (with respect to the plane orientation vector), while
-1
discards elements behind the plane.
|
Viewer
:
this
Destroys all lights.
Viewer
:
This viewer
Sets light sources to defaults.
Viewer
:
this
(any)
Viewer
:
Gets a JSON bookmark of the viewer's current state.
The viewer can then be restored to the bookmark at any time using #setBookmark.
For compactness, a bookmark only contains state that has non-default values.
Object
:
A JSON bookmark.
Sets viewer state to the snapshot contained in given JSON bookmark.
A bookmark is a complete snapshot of the viewer's state, which was captured earlier with #getBookmark. Setting a bookmark will clear everything in the viewer first.
Viewer
:
this
Captures a snapshot image of the viewer's canvas.
(any?)
Capture options.
Name | Description |
---|---|
params.width Number?
|
Desired width of result in pixels - defaults to width of canvas. |
params.height Number?
|
Desired height of result in pixels - defaults to height of canvas. |
params.format String?
(default "jpeg" )
|
Desired format; "jpeg", "png" or "bmp". |
(Function)
Callback to return the image data.
String
:
String-encoded image data when taking the snapshot synchronously. Returns null when the
ok
callback is given.
viewer.getSnapshot({
width: 500,
height: 500,
format: "png"
}, function(imageDataURL) {
imageElement.src = imageDataURL;
});
Clears and destroys this viewer.
(any)
Viewer
:
this