Class Shape<UserData>

An entity that displays a geometric shape made of connected vertices.

Shape components

A shape is made of several optional components:

  • vertices
  • main line
  • secondary lines
  • surface
  • labels

All components can be hidden. In that case the shape displays nothing, even though its visible property is set to true.

Vertices

Vertices can be displayed for each point of the shape.

const shape = new Shape(...);

shape.showVertices = true;
shape.vertexRadius = 12; // pixels

Note: vertices do not have to be displayed for the points to be editable.

Main line

The main line is the line that connects the points of the shape. This line can form a ring if the shape is closed (with the makeClosed() method).

Note: the main line can only be displayed if there are 2 or more vertices.

Surface

If the main line is a ring, the surface can be displayed by toggling showSurface. The surface has the same color as the shape, but its opacity can be changed with surfaceOpacity.

Note: the surface can only be displayed if there are 4 or more vertices (and the first and last vertices must be equal).

Secondary lines

Secondary lines are:

  • vertical lines that connect each vertex to the floor elevation, toggled with showVerticalLines
  • the horizontal line that connect each floor vertex, toggled by showFloorLine

The elevation of the floor can be set with floorElevation.

Floor vertices

Floor vertices are a secondary set of uneditable vertices that connect each main vertex to the floor elevation. They can be toggled with showFloorVertices.

Styling

The shape can be styled with different parameters:

  • color to set the color of all element of the shape, including labels.
  • lineWidth to set the width of the lines, in pixels.
  • vertexRadius to set the radius of vertices, in pixels.
  • borderWidth to set the width of the border, in pixels.
  • dashSize to change the size of the dashes of secondary lines

Note: the border color is automatically computed to provide sufficient contrast from the main color.せtぽい

Labels

Labels can be displayed for various areas of the shape:

Label styling

Labels are DOM elements and are styled with three properties:

Label formatting

The text of each label is provided by a Formatter. The formatter either returns a string or null. If null, the label is not displayed at all.

Type Formatter Default formatter
vertices VertexLabelFormatter Displays the vertex index
segments SegmentLabelFormatter Displays the length of the segment in metric units
line LineLabelFormatter Displays the length of the line in metric units
vertical lines VerticalLineLabelFormatter Displays the length of the line in metric units
surface SurfaceLabelFormatter Displays the area of the surface in square metric units

Formatter examples

To display the parity of the vertex index:

const parityFormatter = ({ vertexIndex }) => {
    if (vertexIndex % 2 === 0) {
        return 'even vertex';
    } else {
        return 'odd vertex';
    }
}

const shape = new Shape({
    ...options,
    vertexLabelFormatter: parityFormatter
});

To display the length of segments in feet:

const feetFormatter = ({ length }) => {
    return `${length * 3.28084} ft`;
}

const shape = new Shape({
    ...options,
    segmentLabelFormatter: feetFormatter
});

To display the area of the surface in acres:

const acresFormatter = ({ area }) => {
    return `${area * 0.000247105} acres`;
}

const shape = new Shape({
    ...options,
    surfaceLabelFormatter: acresFormatter
});

Hooks

Each operation that modifies the list of the points (updatePoint, removePoint, insertPoint, but not setPoints) triggers two hooks:

The PreHook can be used to cancel the operation by returning false.

Hooks can be used to enforce constraints. For example to prevent removal of points such that the number of points becomes insufficient to represent a polygon.

const beforeRemovePoint = ({ shape }) => {
    // Prevent removal of points if we are already at the
    // minimum number of vertices to display a polygon
    if (shape.points.length < 4) {
        return false;
    }

    return true;
}

PostHooks can be used to update the shape after an operation.

For example, suppose we have a 2-point shape, and we want to ensure that both points have the same elevation (Z coordinate). Whenever a point is moved, we might also want to update the other point.

const afterUpdatePoint = ({ shape, index, newPosition }) => {
    const z = newPosition.z;

    const otherIndex = index === 0 ? 1 : 0;
    const other = shape.points[otherIndex];

    // Prevent infinite recursion by checking that
    // the point is not already at the correct height.
    if (other.z !== z) {
        shape.updatePoint(otherIndex, new Vector3(other.x, other.y, z));
    }
}

const shape = new Shape({
    ...options,
    afterUpdatePoint,
});

Type Parameters

Hierarchy (view full)

Constructors

constructor

Properties

_distance id isEntity isEntity3D isMemoryUsage isPickable isShape name type userData

Accessors

borderWidth clippingPlanes color dashSize dashed depthTest distance floorElevation fontSize fontWeight frozen instance isClosed labelOpacity lineWidth loading object3d opacity pickableLabels points progress ready renderOrder showFloorLine showFloorVertices showLine showLineLabel showSegmentLabels showSurface showSurfaceLabel showVertexLabels showVerticalLineLabels showVerticalLines showVertices surfaceOpacity vertexRadius visible

Methods

addEventListener assignRenderOrder contains dispatchEvent dispose filterChangeSources getArea getBoundingBox getClosestPointOnLine getLength getMemoryUsage getNextPoint getPreviousPoint hasEventListener insertPoint isOwned makeClosed notifyChange onObjectCreated onRenderingContextLost onRenderingContextRestored pick postUpdate preUpdate preprocess rebuildLabels removeEventListener removePoint setPoints setupMaterial shouldCheckForUpdate shouldFullUpdate shouldUpdate toGeoJSON toOpenLayersFeature traverse traverseMaterials traverseMeshes update updateClippingPlanes updateOpacity updatePoint updateRenderOrder updateVisibility

Constructors

constructor

Properties

Protected _distance

_distance: {
    max: number;
    min: number;
}

Type declaration

  • max: number
  • min: number

Readonly id

id: string

The unique identifier of this entity.

Readonly isEntity

isEntity: boolean = ...

Read-only flag to check if a given object is of type Entity.

Readonly isEntity3D

isEntity3D: boolean = ...

Read-only flag to check if a given object is of type Entity3D.

Readonly isMemoryUsage

isMemoryUsage: true = ...

Readonly isPickable

isPickable: true = true

Readonly isShape

isShape: true = ...

name

name: undefined | string

The name of this entity.

Readonly type

type: "Shape" = ...

The name of the type of this object.

Readonly userData

userData: UserData

An object that can be used to store custom data about the Entity.

Accessors

borderWidth

clippingPlanes

  • get clippingPlanes(): null | Plane[]

  • Gets or sets the clipping planes set on this entity. Default is null (no clipping planes).

    Note: custom entities must ensure that the materials and shaders used do support the clipping plane feature of three.js. Refer to the three.js documentation for more information.

    Returns null | Plane[]

  • set clippingPlanes(planes): void

  • Parameters

    Returns void

color

dashSize

dashed

depthTest

distance

  • get distance(): {
        max: number;
        min: number;
    }

  • Returns {
        max: number;
        min: number;
    }

    • max: number
    • min: number

floorElevation

fontSize

  • get fontSize(): number

  • Gets or sets the font size, in pixels.

    Returns number

    Default Value

    {@link DEFAULT_FONT_SIZE}
  • set fontSize(v): void

  • Parameters

    • v: number

    Returns void

fontWeight

frozen

  • get frozen(): boolean

  • Gets or sets the frozen status of this entity. A frozen entity is still visible but will not be updated automatically.

    Useful for debugging purposes.

    Returns boolean

  • set frozen(v): void

  • Parameters

    • v: boolean

    Returns void

instance

isClosed

labelOpacity

  • get labelOpacity(): number

  • Gets or sets the opacity factor of the labels. The final opacity of the label is the product of this value with opacity.

    Returns number

  • set labelOpacity(v): void

  • Parameters

    • v: number

    Returns void

lineWidth

loading

  • get loading(): boolean

  • Gets whether this entity is currently loading data.

    Returns boolean

object3d

opacity

  • get opacity(): number

  • Gets or sets the opacity of this entity.

    Returns number

  • set opacity(v): void

  • Parameters

    • v: number

    Returns void

pickableLabels

points

progress

  • get progress(): number

  • Gets the current loading progress (between 0 and 1). Note: This property is only meaningful if loading is true.

    Returns number

ready

  • get ready(): boolean

  • Determine if this entity is ready to use.

    Returns boolean

renderOrder

  • get renderOrder(): number

  • Gets or sets the render order of this entity.

    Returns number

  • set renderOrder(v): void

  • Parameters

    • v: number

    Returns void

showFloorLine

showFloorVertices

showLine

showLineLabel

showSegmentLabels

showSurface

showSurfaceLabel

showVertexLabels

showVerticalLineLabels

  • get showVerticalLineLabels(): boolean

  • Toggle the vertical line labels (one label per vertical line).

    Returns boolean

  • set showVerticalLineLabels(show): void

  • Parameters

    • show: boolean

    Returns void

showVerticalLines

  • get showVerticalLines(): boolean

  • Toggle the display of vertical distances (distances from each vertex to a defined elevation).

    Returns boolean

  • set showVerticalLines(show): void

  • Parameters

    • show: boolean

    Returns void

showVertices

surfaceOpacity

  • get surfaceOpacity(): number

  • Gets or sets the specific opacity factor of the surface. The final opacity of the surface is the product of this value with opacity.

    Returns number

  • set surfaceOpacity(v): void

  • Parameters

    • v: number

    Returns void

vertexRadius

  • get vertexRadius(): number

  • Gets or sets the radius of the vertices, in pixels.

    Returns number

  • set vertexRadius(radius): void

  • Parameters

    • radius: number

    Returns void

visible

  • get visible(): boolean

  • Gets or sets the visibility of this entity. A non-visible entity will not be automatically updated.

    Returns boolean

  • set visible(v): void

  • Parameters

    • v: boolean

    Returns void

Methods

addEventListener

Protected assignRenderOrder

contains

  • contains(obj): boolean

  • Test whether this entity contains the given object.

    The object may be a component of the entity, or a 3D object.

    Parameters

    • obj: unknown

      The object to test.

    Returns boolean

    true if the entity contains the object.

dispatchEvent

dispose

filterChangeSources

getArea

  • getArea(): null | number

  • Gets the area of this shape, if any.

    Note: if the shape is not a closed shape, returns null.

    Returns null | number

    The area, in CRS units.

getBoundingBox

getClosestPointOnLine

  • getClosestPointOnLine(point): {
        point: Vector3;
        previousPointIndex: number;
    }

  • Returns the closest point on the line to the specified point.

    Parameters

    Returns {
        point: Vector3;
        previousPointIndex: number;
    }

    An object containing the location of the closest point, as well as the index of the first point that makes the segment in which the point was found.

    • point: Vector3
    • previousPointIndex: number

getLength

  • getLength(): null | number

  • Gets the length of the line of this shape, if any. If the shape has less than 2 points, returns null.

    Note: if the shape is a closed shape, this equals the perimeter of the shape.

    Returns null | number

    The length, in CRS units.

getMemoryUsage

getNextPoint

  • getNextPoint(index): null | Vector3

  • Returns the point just after the specified index, taking into account closed lines.

    Parameters

    • index: number

      The point index.

    Returns null | Vector3

    The location of the next point, if any, otherwise null.

    Note: if the line is not closed, requesting the point after index (n - 1) will return null, but if the line is closed, it will return the point after the first one.

getPreviousPoint

  • getPreviousPoint(index): null | Vector3

  • Returns the point just before the specified index, taking into account closed lines.

    Parameters

    • index: number

      The point index.

    Returns null | Vector3

    The location of the previous point, if any, otherwise null.

    Note: if the line is not closed, requesting the point before index zero will return null, but if the line is closed, it will return the point before the last one.

hasEventListener

insertPoint

  • insertPoint(index, position): void

  • Inserts a point at the specified index.

    Parameters

    • index: number

      The point index.

    • position: Vector3

      The position of the point.

    Returns void

Protected isOwned

  • isOwned(obj): boolean

  • Returns true if this object belongs to this entity.

    Parameters

    • obj: unknown

      The object to test.

    Returns boolean

makeClosed

  • makeClosed(): void

  • Ensures that the line makes a closed ring, by duplicating the first point as the last point, if necessary.

    Returns void

Protected notifyChange

onObjectCreated

  • onObjectCreated(obj): void

  • Applies entity-level setup on a new object.

    Note: this method should be called from the subclassed entity to notify the parent class that a new 3D object has just been created, so that it can be setup with entity-wide parameters.

    Parameters

    Returns void

    Example

    // In the subclass
    const obj = new Object3D();

    // Notify the parent class
    this.onObjectCreated(obj);

onRenderingContextLost

  • onRenderingContextLost(options): void

  • Called when the rendering context has been lost.

    Parameters

    • options: {
          canvas: HTMLCanvasElement;
      }

      The options.

      • canvas: HTMLCanvasElement

    Returns void

onRenderingContextRestored

pick

postUpdate

  • postUpdate(context, changeSources): void

  • Method called after Entity.update.

    Parameters

    • context: Context

      the update context.

    • changeSources: Set<unknown>

      the objects that triggered an update step. This is useful to filter out unnecessary updates if no sources are relevant to this entity. For example, if one of the sources is a camera that moved during the previous frame, any entity that depends on the camera's field of view should be updated.

    Returns void

preUpdate

  • preUpdate(): null | unknown[]

  • This method is called just before update() to filter and select which elements should be actually updated. For example, in the case of complex entities made of a hierarchy of elements, the entire hierarchy may not need to be updated.

    Use this method to optimize the update step by reducing the number of elements to process.

    Note: if this functions returns nothing, update() will not be called.

    Returns null | unknown[]

    the elements to update during update().

Protected preprocess

  • preprocess(_opts): Promise<void>

  • Asynchronously preprocess the entity. This method may be overriden to perform any operation that must be done before the entity can be used in the scene, such as fetching metadata about a dataset, etc.

    Parameters

    • _opts: EntityPreprocessOptions

    Returns Promise<void>

    A promise that resolves when the entity is ready to be used.

rebuildLabels

  • rebuildLabels(): void

  • Rebuilds all labels. Useful if the formatter functions have changed.

    Returns void

removeEventListener

removePoint

  • removePoint(index): void

  • Removes the point at the given index.

    Parameters

    • index: number

      The index of the point to update.

    Returns void

setPoints

  • setPoints(points?): void

  • Sets the points of the shape.

    Parameters

    • Optional points: Vector3[]

      The points. If null, all points are removed.

    Returns void

Protected setupMaterial

  • setupMaterial(material): void

  • Applies entity-level setup on new object's material.

    Subclasses can override this to setup custom logic, for instance if the entity can produce objects that are naturally transparent.

    Parameters

    • material: Material

      the material of the newly created object

    Returns void

shouldCheckForUpdate

  • shouldCheckForUpdate(): boolean

  • This method is called before update to check if the MainLoop should try to update this entity or not. For better performances, it should return false if the entity has no impact on the rendering (e.g. the element is not visible).

    The inherited child can completely ignore this value if it makes sense.

    Returns boolean

    true if should check for update

shouldFullUpdate

  • shouldFullUpdate(updateSource): boolean

  • This method is called at the beginning of the update step to determine if we should do a full render of the object. This should be the case if, for instance, the source is the camera.

    You can override this depending on your needs. The inherited child should not ignore this value, it should do a boolean OR, e.g.: return super.shouldFullUpdate(updateSource) || this.contains(updateSource);

    Parameters

    • updateSource: unknown

      Source of change

    Returns boolean

    true if requires a full update of this object

shouldUpdate

  • shouldUpdate(updateSource): boolean

  • This method is called at the beginning of the update step to determine if we should re-render updateSource. Not used when shouldFullUpdate returns true.

    You can override this depending on your needs. The inherited child should not ignore this value, it should do a boolean OR, e.g.: return super.shouldUpdate(updateSource) || this.contains(updateSource);

    Parameters

    • updateSource: unknown

      Source of change

    Returns boolean

    true if requires an update of updateSource

toGeoJSON

  • toGeoJSON(options?): Feature<Geometry, GeoJsonProperties>

  • Returns the GeoJSON (in WGS84 coordinates) feature equivalent to this shape.

    Parameters

    Returns Feature<Geometry, GeoJsonProperties>

toOpenLayersFeature

traverse

traverseMaterials

  • traverseMaterials(callback, root?): void

  • Traverses all materials in the hierarchy of this entity.

    Parameters

    • callback: ((arg0) => void)

      The callback.

        • (arg0): void

        • Parameters

          Returns void

    • root: undefined | Object3D<Object3DEventMap> = undefined

      The traversal root. If undefined, the traversal starts at the root object of this entity.

    Returns void

traverseMeshes

update

  • update(context, element): undefined | null | unknown[]

  • Performs an update on an element of the entity.

    Note: this method will be called for each element returned by preUpdate().

    Parameters

    • context: Context

      the update context. This is the same object that the entity whose update() is being called.

    • element: unknown

      the element to update. This is one of the elements returned by preUpdate.

    Returns undefined | null | unknown[]

    New elements to update

updateClippingPlanes

updateOpacity

updatePoint

  • updatePoint(index, newPosition): void

  • Sets the position of an existing point.

    Parameters

    • index: number

      The index of the point to update.

    • newPosition: Vector3

      The new position of the point.

    Returns void

updateRenderOrder

updateVisibility

Settings

Member Visibility

On This Page

constructor_distanceidisEntityisEntity3DisMemoryUsageisPickableisShapenametypeuserDataborderWidthclippingPlanescolordashSizedasheddepthTestdistancefloorElevationfontSizefontWeightfrozeninstanceisClosedlabelOpacitylineWidthloadingobject3dopacitypickableLabelspointsprogressreadyrenderOrdershowFloorLineshowFloorVerticesshowLineshowLineLabelshowSegmentLabelsshowSurfaceshowSurfaceLabelshowVertexLabelsshowVerticalLineLabelsshowVerticalLinesshowVerticessurfaceOpacityvertexRadiusvisibleaddEventListenerassignRenderOrdercontainsdispatchEventdisposefilterChangeSourcesgetAreagetBoundingBoxgetClosestPointOnLinegetLengthgetMemoryUsagegetNextPointgetPreviousPointhasEventListenerinsertPointisOwnedmakeClosednotifyChangeonObjectCreatedonRenderingContextLostonRenderingContextRestoredpickpostUpdatepreUpdatepreprocessrebuildLabelsremoveEventListenerremovePointsetPointssetupMaterialshouldCheckForUpdateshouldFullUpdateshouldUpdatetoGeoJSONtoOpenLayersFeaturetraversetraverseMaterialstraverseMeshesupdateupdateClippingPlanesupdateOpacityupdatePointupdateRenderOrderupdateVisibility