Reference Source
public class | source

ImagePlane

Extends:

Component → ImagePlane

A plane-shaped 3D object containing a bitmap image.

Use ImagePlane to embed bitmap images in your scenes.

As shown in the examples below, ImagePlane is useful for creating ground planes from satellite maps and embedding 2D plan view images in cross-section slicing planes.

Example 1: Create a ground plane from a satellite image

In our first example, we'll load the Schependomlaan model, then use an ImagePlane to create a ground plane, which will contain a satellite image sourced from Google Maps.

[Run this example]

import {Viewer} from "../src/viewer/Viewer.js";
import {ImagePlane} from "../src/viewer/scene/ImagePlane/ImagePlane.js";
import {XKTLoaderPlugin} from "../src/plugins/XKTLoaderPlugin/XKTLoaderPlugin.js";

const viewer = new Viewer({
     canvasId: "myCanvas",
     transparent: true
 });

viewer.camera.eye = [-8.31, 42.21, 54.30];
viewer.camera.look = [-0.86, 15.40, 14.90];
viewer.camera.up = [0.10, 0.83, -0.54];

const xktLoader = new XKTLoaderPlugin(viewer);

xktLoader.load({             // Load IFC model
     id: "myModel",
     src: "./models/xkt/schependomlaan/schependomlaan.xkt",
     metaModelSrc: "./metaModels/schependomlaan/metaModel.json",
     edges: true,

     rotation: [0, 22, 0],   // Rotate, position and scale the model to align it correctly with the ImagePlane
     position: [-8, 0, 15],
     scale: [1.1, 1.1, 1.1]
 });

new ImagePlane(viewer.scene, {
     src: "./images/schependomlaanSatMap.png",       // Google satellite image; accepted file types are PNG and JPEG
     visible: true,                                  // Show the ImagePlane
     gridVisible: true,                              // Show the grid - grid is only visible when ImagePlane is also visible
     size: 190,                                      // Size of ImagePlane's longest edge
     position: [0, -1, 0],                           // World-space position of ImagePlane's center
     rotation: [0, 0, 0],                            // Euler angles for X, Y and Z
     opacity: 1.0,                                   // Fully opaque
     collidable: false,                              // ImagePlane does not contribute to Scene boundary
     clippable: true,                                // ImagePlane can be clipped by SectionPlanes
     pickable: true                                  // Allow the ground plane to be picked
});


Example 2: Embed an image in a cross-section plane

In our second example, we'll load the Schependomlaan model again, then slice it in half with a SectionPlanesPlugin, then use an ImagePlane to embed a 2D plan view image in the slicing plane.

[Run this example]

import {Viewer} from "../src/viewer/Viewer.js";
import {XKTLoaderPlugin} from "../src/plugins/XKTLoaderPlugin/XKTLoaderPlugin.js";
import {SectionPlanesPlugin} from "../src/plugins/SectionPlanesPlugin/SectionPlanesPlugin.js";
import {ImagePlane} from "../src/viewer/scene/ImagePlane/ImagePlane.js";

const viewer = new Viewer({
    canvasId: "myCanvas",
    transparent: true
});

viewer.camera.eye = [-9.11, 20.01, 5.13];
viewer.camera.look = [9.07, 0.77, -9.78];
viewer.camera.up = [0.47, 0.76, -0.38];

const xktLoader = new XKTLoaderPlugin(viewer);

const sectionPlanes = new SectionPlanesPlugin(viewer, {
    overviewVisible: false
});

model = xktLoader.load({
    id: "myModel",
    src: "./models/xkt/schependomlaan/schependomlaan.xkt",
    metaModelSrc: "./metaModels/schependomlaan/metaModel.json",
    edges: true,
});

const sectionPlane = sectionPlanes.createSectionPlane({
    id: "mySectionPlane",
    pos: [10.95, 1.95, -10.35],
    dir: [0.0, -1.0, 0.0]
});

const imagePlane = new ImagePlane(viewer.scene, {
    src: "./images/schependomlaanPlanView.png",  // Plan view image; accepted file types are PNG and JPEG
    visible: true,
    gridVisible: true,
    size: 23.95,
    position: sectionPlane.pos,
    dir: sectionPlane.dir,
    collidable: false,
    opacity: 0.75,
    clippable: false,                            // Don't allow ImagePlane to be clipped by the SectionPlane
    pickable: false                              // Don't allow ImagePlane to be picked
 });

Constructor Summary

Public Constructor
public

constructor(owner: Component, cfg: *)

Member Summary

Public Members
public set

Sets if this ImagePlane is clippable.

public get

Gets if this ImagePlane is clippable.

public set

Sets if this ImagePlane is included in boundary calculations.

public get

Gets if this ImagePlane is included in boundary calculations.

public set

dir(dir: Number[])

Sets the direction of this ImagePlane as a direction vector.

public get

dir: Number[]: *

Gets the direction of this ImagePlane as a direction vector.

public set

gridVisible(visible: Boolean)

Sets if this ImagePlane's grid is visible or not.

Default value is false.

Grid is only visible when ImagePlane is also visible.

public get

Gets if this ImagePlane's grid is visible or not.

Default value is false.

public set

image: HTMLImageElement

Sets an HTMLImageElement to source the image from.

public get

image: HTMLImageElement

Gets the HTMLImageElement the ImagePlane's image is sourced from, if set.

Returns null if not set.

public set

Sets the opacity factor for this ImagePlane.

public get

Gets this ImagePlane's opacity factor.

This is a factor in range [0..1] which multiplies by the rendered fragment alphas.

public set

Sets if this ImagePlane is pickable.

public get

Gets if this ImagePlane is pickable.

public set

position(value: Number[])

Sets the World-space position of this ImagePlane.

public get

Gets the World-space position of this ImagePlane.

public set

rotation(value: Number[])

Sets the direction of this ImagePlane using Euler angles.

public get

Gets the direction of this ImagePlane as Euler angles.

public set

size(size: Number)

Sets the World-space size of the longest edge of the ImagePlane.

public get

size: *

Gets the World-space size of the longest edge of the ImagePlane.

public set

Sets an image file path that the ImagePlane's image is sourced from.

Accepted file types are PNG and JPEG.

Sets Texture#image null.

public get

Gets the image file path that the ImagePlane's image is sourced from, if set.

Returns null if not set.

public set

visible(visible: Boolean)

Sets if this ImagePlane is visible or not.

public get

Gets if this ImagePlane is visible or not.

Method Summary

Public Methods
public

Inherited Summary

From class Component
public get

The Component that owns the lifecycle of this Component, if any.

public

True as soon as this Component has been destroyed

public

ID of this Component, unique within the Scene.

public

meta: *

Arbitrary, user-defined metadata on this component.

public

The parent Scene that contains this Component.

public

The viewer that contains this Scene.

public

clear()

Destroys all Components that are owned by this.

public

Destroys this component.

public

error(message: String)

Logs an error for this component to the JavaScript console.

public

fire(event: String, value: Object, forget: Boolean)

Fires an event on this component.

public

Returns true if there are any subscribers to the given event on this component.

public

isType(type: *): *: Boolean

Tests if this component is of the given type, or is a subclass of the given type.

public

log(message: String)

Logs a console debugging message for this component.

public

off(subId: String)

Cancels an event subscription that was previously made with Component#on or Component#once.

public

on(event: String, callback: Function, scope: Object): String

Subscribes to an event on this component.

public

once(event: String, callback: Function, scope: Object)

Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is subIdd.

public

warn(message: String)

Logs a warning for this component to the JavaScript console.

Public Constructors

public constructor(owner: Component, cfg: *) source

Override:

Component#constructor

Params:

NameTypeAttributeDescription
owner Component
  • optional

Owner component. When destroyed, the owner will destroy this ImagePlane as well.

cfg *
  • optional

ImagePlane configuration

cfg.id String
  • optional

Optional ID, unique among all components in the parent Scene, generated automatically when omitted.

cfg.visible Boolean
  • optional
  • default: true

Indicates whether or not this ImagePlane is visible.

cfg.gridVisible Boolean
  • optional
  • default: true

Indicates whether or not the grid is visible. Grid is only visible when ImagePlane is also visible.

cfg.position Number[]
  • optional
  • default: [0,0,0]

World-space position of the ImagePlane.

cfg.size Number[]
  • optional
  • default: 1

World-space size of the longest edge of the ImagePlane. Note that ImagePlane sets its aspect ratio to match its image. If we set a value of 1000, and the image has size 400x300, then the ImagePlane will then have size 1000 x 750.

cfg.rotation Number[]
  • optional
  • default: [0,0,0]

Local rotation of the ImagePlane, as Euler angles given in degrees, for each of the X, Y and Z axis.

cfg.matrix Number[]
  • optional
  • default: [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]

Modelling transform matrix for the ImagePlane. Overrides the position, size```,rotationanddir parameters.

cfg.collidable Boolean
  • optional
  • default: true

Indicates if the ImagePlane is initially included in boundary calculations.

cfg.clippable Boolean
  • optional
  • default: true

Indicates if the ImagePlane is initially clippable.

cfg.pickable Boolean
  • optional
  • default: true

Indicates if the ImagePlane is initially pickable.

cfg.opacity Number
  • optional
  • default: 1.0

ImagePlane's initial opacity factor, multiplies by the rendered fragment alpha.

cfg.src String
  • optional

URL of image. Accepted file types are PNG and JPEG.

cfg.image HTMLImageElement
  • optional

An HTMLImageElement to source the image from. Overrides src.

Public Members

public set clippable: Boolean source

Sets if this ImagePlane is clippable.

Clipping is done by the SectionPlanes in Scene#sectionPlanes.

Default is true.

public get clippable: Boolean source

Gets if this ImagePlane is clippable.

Clipping is done by the SectionPlanes in Scene#sectionPlanes.

Default is true.

public set collidable: Boolean source

Sets if this ImagePlane is included in boundary calculations.

Default is true.

public get collidable: Boolean source

Gets if this ImagePlane is included in boundary calculations.

Default is true.

public set dir(dir: Number[]) source

Sets the direction of this ImagePlane as a direction vector.

Default value is [0, 0, -1].

public get dir: Number[]: * source

Gets the direction of this ImagePlane as a direction vector.

Return:

Number[]

value Current direction.

public set gridVisible(visible: Boolean) source

Sets if this ImagePlane's grid is visible or not.

Default value is false.

Grid is only visible when ImagePlane is also visible.

public get gridVisible: Boolean: * source

Gets if this ImagePlane's grid is visible or not.

Default value is false.

Return:

Boolean

Returns true if visible.

public set image: HTMLImageElement source

Sets an HTMLImageElement to source the image from.

Sets Texture#src null.

public get image: HTMLImageElement source

Gets the HTMLImageElement the ImagePlane's image is sourced from, if set.

Returns null if not set.

public set opacity: Number source

Sets the opacity factor for this ImagePlane.

This is a factor in range [0..1] which multiplies by the rendered fragment alphas.

public get opacity: Number source

Gets this ImagePlane's opacity factor.

This is a factor in range [0..1] which multiplies by the rendered fragment alphas.

public set pickable: Boolean source

Sets if this ImagePlane is pickable.

Default is true.

public get pickable: Boolean source

Gets if this ImagePlane is pickable.

Default is true.

public set position(value: Number[]) source

Sets the World-space position of this ImagePlane.

Default value is [0, 0, 0].

public get position: Number[]: * source

Gets the World-space position of this ImagePlane.

Default value is [0, 0, 0].

Return:

Number[]

Current position.

public set rotation(value: Number[]) source

Sets the direction of this ImagePlane using Euler angles.

Default value is [0, 0, 0].

public get rotation: Number[]: * source

Gets the direction of this ImagePlane as Euler angles.

Return:

Number[]

Euler angles for X, Y and Z axis rotations.

public set size(size: Number) source

Sets the World-space size of the longest edge of the ImagePlane.

Note that ImagePlane sets its aspect ratio to match its image. If we set a value of 1000, and the image has size 400x300, then the ImagePlane will then have size 1000 x 750.

Default value is 1.0.

public get size: * source

Gets the World-space size of the longest edge of the ImagePlane.

Returns {Number} World-space size of the ImagePlane.

public set src: String source

Sets an image file path that the ImagePlane's image is sourced from.

Accepted file types are PNG and JPEG.

Sets Texture#image null.

public get src: String source

Gets the image file path that the ImagePlane's image is sourced from, if set.

Returns null if not set.

public set visible(visible: Boolean) source

Sets if this ImagePlane is visible or not.

Default value is true.

public get visible: Boolean: * source

Gets if this ImagePlane is visible or not.

Default value is true.

Return:

Boolean

Returns true if visible.

Public Methods

public destroy() source

Destroys this component.

Override:

Component#destroy