Interface CutPlaneManagerInterface

The CutPlaneManagerInterface interface is used to create cut planes, that are used to hide half of the scene.

The CutPlaneManagerInterface is included in the InfiniteEngineInterface and accessed through InfiniteEngineInterface.getCutPlaneManager.

There are no javascript cut plane objects, cut planes are modified through the CutPlaneManagerInterface by their ids. Indeed, each cut plane is assigned an integer id upon its creation, 0 is an invalid id, and is the expected result if the cut plan creation fails. Ids are recycled upon cut planes deletion, so there may be cases when a new cut plane is assigned an id that belonged to a deleted cut plane.

There is a limited number of cut planes that may be created by an application (shader limitations) : only 16 different cut planes may be created / manipulated (getMaxCutPlanesCount).

A cut plane is defined by a position P that belong to the plane and a normal N : (Nx,Ny,Nz). This defines a plane (hyperplane) in 3D dimension. Such a plane has the equation : {x,y,z} / Nx.x + Ny.y + Nz.z = dot(N,P). Each vertex on the side of the normal N will be discarded, so every vertex V : {Vx,Vy,Vz} / Nx.Vx + Ny.Vy + Nz.Vz > dot(N,P) will be discarded.

When an equation is provided, the reference point is the projection of the center of the DMU to this cut plane. The equation is a Vector4(a,b,c,d) such that all points P(x,y,z) satisfy the equation : ax + by + cz = d.

A CutPlaneManipulatorInterface may be created and bound to a cut plane to display a GUI element that allows the end user to change the cut plane orientation / position through CutPlaneManagerInterface.createCutPlaneManipulator.

Cut planes can be grouped together, in this case, a 3D point is considered 'cut' when its position is in the cut half plane of ALL the cut planes that belong to the same group. By default, cut planes are assigned the group 0 which is not a cut plane group. The 0 group is the default behavior of cut planes. There is a limited number of cut plane groups (shader limitation), only 7 real cut plane groups exist, ranging from 1 to 7 included. Groups are set with setCutPlaneGroup.

When a cut plane is modified or disabled/enabled, CutPlaneManagerInterfaceSignal signals are sent.

Suppose that we want to hide all items whose "altitude" (z) is superior to 10.

/** 
 * Sample to illustrate the creation of a cut plane, manipulated with a CutPlaneManipulatorInterface.
 */
import { InfiniteEngineInterface, CutPlaneManagerInterface, Vector3, CutPlaneManipulatorInterface } from 'generated_files/documentation/appinfiniteapi';

// lEngine has been created previously
let lEngine : InfiniteEngineInterface;

// we want to hide items that are above (and not under), thus the normal is in the positive side.
const lNormal : Vector3 = new Vector3(0, 0, 1);
// any point with z = 10 is ok
const lPoint : Vector3 = new Vector3(Math.random(), Math.random(), 10);
// get the cut plane manager
const lCutPlaneManager : CutPlaneManagerInterface = lEngine.getCutPlaneManager();
const lCutPlaneId = lCutPlaneManager.createCutPlane(lPoint, lNormal);
console.assert(lCutPlaneId !== 0);
// do what you want, the cut plane is working as it is enabled upon creation
// and create a cut plane manipulator to allow the end user to change the cut plane geometry.
const lCutPlaneManipulator : CutPlaneManipulatorInterface = lCutPlaneManager.createCutPlaneManipulator();
// bind the manipulator to the newly created cut plane
lCutPlaneManipulator.setCutPlaneId(lCutPlaneId);
// hide it for the moment, we may need it later
lCutPlaneManipulator.setVisible(false);

Please refer to the CutPlaneManipulatorInterface for more information.

3D Rendering

See

interface CutPlaneManagerInterface {
    addEventListener(pType, pListener, pObject): string;
    addEventListener(pType, pListener): string;
    areSignalsBlocked(): boolean;
    blockSignals(pBlock): void;
    createCutPlane(pPoint, pNormal): number;
    createCutPlaneFromEquation(pEquation): number;
    createCutPlaneManipulator(): CutPlaneManipulatorInterface;
    fromJSON(pCutPlaneData): boolean;
    getCutPlaneEquation(pCutPlaneId, pCutPlaneEquation): boolean;
    getCutPlaneGeometry(pCutPlaneId, pCutPlanePoint, pCutPlaneNormal): boolean;
    getCutPlaneGroup(pCutPlaneId): number;
    getCutPlanesCount(): number;
    getCutPlanesIds(): number[];
    getMaxCutPlanesCount(): number;
    hasEventListener(pType, pListener): boolean;
    hasEventListenerById(pId): boolean;
    isCutPlaneEnabled(pCutPlaneId): boolean;
    removeAllCutPlanes(): void;
    removeAllEventListeners(): boolean;
    removeCutPlane(pCutPlaneId): boolean;
    removeEventListener(pType, pListener, pObject): boolean;
    removeEventListener(pType, pListener): boolean;
    removeEventListenerById(pId): boolean;
    setCutPlaneEnabled(pCutPlaneId, pEnabled): boolean;
    setCutPlaneGroup(pCutPlaneId, pCutPlaneGroup): boolean;
    toJSON(pKey?): Object;
    updateCutPlaneGeometry(pCutPlaneId, pPoint, pNormal): boolean;
    updateCutPlaneGeometryFromEquation(pCutPlaneId, pEquation): boolean;
}

Hierarchy (view full)

EventDispatcherInterface
- CutPlaneManagerInterface

Methods

addEventListener

addEventListener(pType, pListener, pObject): string
Adds a listener to an event type.

When an event of the type pType fires, the callback pListener will be called. This function returns a unique string id that may be used in removeEventListenerById to allow simple listener removal. It is possible to add an object that will be included in the callback to avoid creating too many closures. Calling twice addEventListener with the same parameters results in the second call to be ignored, only unique pairs callback / object are allowed, in order to avoid calling multiple times the same thing.
Parameters
- pType: string
  in
  The type of the event pListener will be called upon.
- pListener: tListenerCallback
  in
  The listener function that fires when the given event type occurs.
- pObject: Object
  in
  The optional object the callback will be called with when the given event fires.
Returns string
The id of the inserted callback (actually an UUID).

Inherited from EventDispatcherInterface.addEventListener
addEventListener(pType, pListener): string
Adds a listener to an event type.

When an event of the type pType fires, the callback pListener will be called. This function returns a unique string id that may be used in removeEventListenerById to allow simple listener removal.
Parameters
- pType: string
  in
  The type of the event pListener will be called upon.
- pListener: tListenerCallback
  in
  The listener function that fires when the given event type occurs.
Returns string
The id of the inserted callback (actually an UUID).

Inherited from EventDispatcherInterface.addEventListener

areSignalsBlocked

areSignalsBlocked(): boolean
Tells if signals sent by the object are blocked or not.

If signals are blocked, no signal will be emitted nor buffered, such signal will be lost.

Returns boolean
true if signals are blocked.

Inherited from EventDispatcherInterface.areSignalsBlocked

blockSignals

blockSignals(pBlock): void
Blocks / Unblocks all signals sent by the object.

If signals are blocked, no signal will be emitted nor buffered, such signal will be lost.
Parameters
- pBlock: boolean
  in
  If set to true, all further signals will be silently discarded.
Returns void
Inherited from EventDispatcherInterface.blockSignals

createCutPlane

createCutPlane(pPoint, pNormal): number
Creates a new plane given a point position and a normal vector.

The normal does not need to be unit length, but a zero vector is invalid. Each vertex on the side of the normal pNormal will be discarded.

Returns the id (non zero) of the newly created cut plane, or 0 if the maximum number of cut planes have already been reached or if pNormal is equal to (0,0,0).

The newly created cut plane is enabled by default.
Parameters
- pPoint: Vector3
  in
  The 3D position of a point that belongs to the plane.
- pNormal: Vector3
  in
  The 3D normal vector of the plane.
Returns number
The id of the created plane. If the maximum number of available cut planes slots has been reached or if pNormal is equal to (0,0,0), returns 0.

createCutPlaneFromEquation

createCutPlaneFromEquation(pEquation): number
Creates a new plane given a plane equation.

Be N : (Nx,Ny, Nz) the normal of the cut plane, Be P a point of the plane, we get the equation : {x,y,z} / Nx.x + Ny.y + Nz.z = dot(N,P). pCutPlaneEquation will be set such as
pCutPlaneEquation.x = Nx
pCutPlaneEquation.y = Ny
pCutPlaneEquation.z = Nz
pCutPlaneEquation.w = dot(N,P).

Returns the id (non zero) of the newly created cut plane, or 0 if the maximum number of cut planes have already been reached or if the normal is equal to (0,0,0).

The newly created cut plane is enabled by default.
Parameters
- pEquation: Vector4
  in
  The cut plane equation used to determine the plane..
Returns number
The id of the created plane. If the maximum number of available cut planes slots has been reached or if pNormal is equal to (0,0,0), returns 0.

createCutPlaneManipulator

createCutPlaneManipulator(): CutPlaneManipulatorInterface
Instantiates a cut plane manipulator.

The CutPlaneManipulatorInterface is a GUI widget that allows a user to change the position/orientation of the cut plane.

Returns CutPlaneManipulatorInterface
A cut plane manipulator object.

See
CutPlaneManipulatorInterface

fromJSON

fromJSON(pCutPlaneData): boolean

Sets the content of the CutPlaneManagerInterface from a former call to toJSON.

Cut plane parameters may be streamed, using the following schema :

{
    "$defs": {
        "cutplane": {
            "additionalProperties": false,
            "properties": {
                "enabled": {
                    "default": true,
                    "description": "If disabled, this filter is completely ignored during all the computations",
                    "example": true,
                    "type": "boolean"
                },
                "group": {
                    "default": 0,
                    "description": "Cut planes may be grouped together. In that case, an area is considered 'cut' if ALL cut planes cut this area.",
                    "example": 0,
                    "maximum": 7,
                    "minimum": 0,
                    "type": "integer"
                },
                "normal": {
                    "$ref": "#/$defs/vec3"
                },
                "point": {
                    "$ref": "#/$defs/vec3"
                }
            },
            "required": [
                "enabled",
                "point",
                "normal"
            ],
            "title": "Cut plane definition",
            "type": "object"
        },
        "cutplanes": {
            "additionalProperties": false,
            "properties": {
                "cutplanes": {
                    "items": {
                        "$ref": "#/$defs/cutplane"
                    },
                    "type": "array"
                },
                "type": {
                    "const": "cutplanes",
                    "type": "string"
                },
                "version": {
                    "description": "Define the version of the object",
                    "example": 1,
                    "type": "integer"
                }
            },
            "required": [
                "type",
                "cutplanes"
            ],
            "title": "Cut planes definition",
            "type": "object"
        },
        "vec3": {
            "description": "Define the coordinates [x,y,z] of a point / vector",
            "items": {
                "type": "number"
            },
            "maxItems": 3,
            "minItems": 3,
            "title": "3D Vector definition",
            "type": "array"
        }
    },
    "$ref": "#/$defs/cutplanes",
    "$schema": "https://json-schema.org/draft-07/schema#"
}

This schema may evolve in the future.

Parameters

pCutPlaneData: string | Object
in
Internal CutPlaneManagerInterface data to set.

Returns boolean

true if the data is set.

See

toJSON

getCutPlaneEquation

getCutPlaneEquation(pCutPlaneId, pCutPlaneEquation): boolean
Gets the cut plane equation of the given plane.

Be N : (Nx,Ny, Nz) the normal of the cut plane, Be P a point of the plane, we get the equation : {x,y,z} / Nx.x + Ny.y + Nz.z = dot(N,P). pCutPlaneEquation will be set such as
pCutPlaneEquation.x = Nx
pCutPlaneEquation.y = Ny
pCutPlaneEquation.z = Nz
pCutPlaneEquation.w = dot(N,P).

Returns false if the cut plane was not found.
Parameters
- pCutPlaneId: number
  in
  The id of the plane to query.
- pCutPlaneEquation: Vector4
  out
  The cut plane equation used to determine the plane.
Returns boolean
true if pCutPlaneId refers to a valid cut plane.

getCutPlaneGeometry

getCutPlaneGeometry(pCutPlaneId, pCutPlanePoint, pCutPlaneNormal): boolean
Gets the point used to determine the given plane position.

Returns false if the cut plane was not found. Returns false if pCutPlaneNormal and pCutPlanePoint are both undefined.
Parameters
- pCutPlaneId: number
  in
  The id of the plane to query.
- pCutPlanePoint: Vector3
  out
  The cut plane point used to determine the plane (set if undefined).
- pCutPlaneNormal: Vector3
  out
  The cut plane normal used to determine the plane (set if undefined).
Returns boolean
true if pCutPlaneId refers to a valid cut plane and pCutPlaneNormal or pCutPlanePoint is not undefined.

getCutPlaneGroup

getCutPlaneGroup(pCutPlaneId): number
Gets the given cut plane group.

Valid groups are values in the [0 : 7] range.

A returned value of 0 means that the given cut plane does not belong to a group. In case of an invalid cut plane, -1 is returned.
Parameters
- pCutPlaneId: number
  in
  The id of the plane to query.
Returns number
The cut plane group the given cut plane belongs to, or -1 if the cut plane does not exist.

getCutPlanesCount

getCutPlanesCount(): number
Gets the actual number of cut planes.

Returns number
The number of created cut planes.

getCutPlanesIds

getCutPlanesIds(): number[]
Gets the actual cut plane ids that have been created.

Returns number[]
const
The ids of the cut planes in use.

getMaxCutPlanesCount

getMaxCutPlanesCount(): number
Gets the maximum number of cut planes that can be created.

This number is constant, it returns 16 at the moment.

Returns number
The maximum number of planes that can be created.

hasEventListener

hasEventListener(pType, pListener): boolean
Tells if the EventDispatcher has such a callback registered for the given event type.
Parameters
- pType: string
  in
  The type of the event to test.
- pListener: tListenerCallback
  in
  The listener function that gets tested.
Returns boolean
true if such a listener is installed for the given type of event.

Inherited from EventDispatcherInterface.hasEventListener

hasEventListenerById

hasEventListenerById(pId): boolean
Tells if the EventDispatcher has such a callback registered for the given callback id.
Parameters
- pId: string
  in
  The id of the callback to test.
Returns boolean
true if such a listener is installed for the given callback id.

Inherited from EventDispatcherInterface.hasEventListenerById

isCutPlaneEnabled

isCutPlaneEnabled(pCutPlaneId): boolean
Tells if the given cut plane is enabled.

Returns false if the cut plane was not found or if the cut plane is disabled.
Parameters
- pCutPlaneId: number
  in
  The id of the plane to query.
Returns boolean
true if the given cut plane exists and is enabled.

removeAllCutPlanes

removeAllCutPlanes(): void
Removes all previously created cut planes.

Returns void

removeAllEventListeners

removeAllEventListeners(): boolean
Removes all the event listeners.

Returns boolean
true if all the callbacks were removed else false.

Inherited from EventDispatcherInterface.removeAllEventListeners

removeCutPlane

removeCutPlane(pCutPlaneId): boolean
Removes the cut plane with id pCutPlaneId.
Parameters
- pCutPlaneId: number
  in
  The id of the cut plane to remove.
Returns boolean
true if the cut plane exists and therefore has been removed.

removeEventListener

removeEventListener(pType, pListener, pObject): boolean
Removes a listener from an event type.

If no such listener is found, then the function returns false and does nothing. You must use the exact parameters that were used in addEventListener to actually remove the listener.
Parameters
- pType: string
  in
  The type of the listener that gets removed.
- pListener: tListenerCallback
  The listener function that gets removed.
- pObject: Object
  The listener object that was used when addEventListener was called.
Returns boolean
true if the callback was removed else false.

Inherited from EventDispatcherInterface.removeEventListener
removeEventListener(pType, pListener): boolean
Removes a listener from an event type.

If no such listener is found, then the function returns false and does nothing. You must use the exact parameters that were used in addEventListener to actually remove the listener.
Parameters
- pType: string
  in
  The type of the listener that gets removed.
- pListener: tListenerCallback
  The listener function that gets removed.
Returns boolean
true if the callback was removed else false.

Inherited from EventDispatcherInterface.removeEventListener

removeEventListenerById

removeEventListenerById(pId): boolean
Removes a listener by its id.

If no such listener is found, then the function returns false and does nothing. You must use the return value of addEventListener to actually remove the listener.
Parameters
- pId: string
  in
  The id returned by the call to addEventListener that you want to remove.
Returns boolean
true if the callback was removed else false.

Inherited from EventDispatcherInterface.removeEventListenerById

setCutPlaneEnabled

setCutPlaneEnabled(pCutPlaneId, pEnabled): boolean
Sets the enabled status of the cut plane.

A disabled cut plane does not cut anything.

Returns false if the cut plane was not found.
Parameters
- pCutPlaneId: number
  in
  The id of the plane to query.
- pEnabled: boolean
  in
  The enabled status of the cutPlane.
Returns boolean
true if pCutPlaneId refers to a valid cut plane.

setCutPlaneGroup

setCutPlaneGroup(pCutPlaneId, pCutPlaneGroup): boolean
Assigns the given cut plane to the given group.

Cut planes can be grouped together in a cut plane group, in this case a 3D point is considered 'cut' when its position is in the cut half plane of ALL the cut planes that belong to the same group. The group 0 is not a "real group", this is the default group that has no special behavior.

Valid groups are values in the [0 : 7] range. Setting a cut plane group of 0 removes the cut plane from its past group.

In case of an invalid group, false is returned. In case of an invalid cut plane, false is returned. `true' is returned if the call succeeded.

@param pCutPlaneId
in
The id of the plane to modify. @param pCutPlaneGroup
in
The new cut plane group to assign the given cut plane. @return true if the call succeeded.
Parameters
- pCutPlaneId: number
- pCutPlaneGroup: number
Returns boolean

toJSON

toJSON(pKey?): Object
Gets a deep copy of the internal data of the CutPlaneManagerInterface.

Please refer to JSON.stringify.
Parameters
- Optional pKey: any
  in
  Unused.
Returns Object
The internal CutPlaneManagerInterface data.

See
fromJSON

updateCutPlaneGeometry

updateCutPlaneGeometry(pCutPlaneId, pPoint, pNormal): boolean
Updates the shape of the plane pCutPlaneId, changes the point position and the normal vector of the given plane.

Returns false if the plane was not found or if pNormal is (0,0,0).
Parameters
- pCutPlaneId: number
  in
  The id of the plane to modify.
- pPoint: Vector3
  in
  The new 3D position of a point of the plane.
- pNormal: Vector3
  in
  The new 3D normal vector of the plane.
Returns boolean
true if the plane was found, pNormal is not (0,0,0) and therefore the plane orientation/position is updated.

updateCutPlaneGeometryFromEquation

updateCutPlaneGeometryFromEquation(pCutPlaneId, pEquation): boolean
Updates the shape of the plane pCutPlaneId, changes the equation of the given plane.

Be N : (Nx,Ny, Nz) the normal of the cut plane, Be P a point of the plane, we get the equation : {x,y,z} / Nx.x + Ny.y + Nz.z = dot(N,P). pCutPlaneEquation will be set such as
pCutPlaneEquation.x = Nx
pCutPlaneEquation.y = Ny
pCutPlaneEquation.z = Nz
pCutPlaneEquation.w = dot(N,P).

Returns false if the plane was not found or if the resulting normal is (0,0,0). The reference point is the projection of the center of the DMU on the given plane equation.
Parameters
- pCutPlaneId: number
  in
  The id of the plane to modify.
- pEquation: Vector4
  in
  The new cut plane equation used to determine the plane.
Returns boolean
true if the plane was found, the resulting normal is not (0,0,0) and therefore the plane orientation/position is updated.

Interface CutPlaneManagerInterface

See

Hierarchy (view full)

Index

Methods

Methods

addEventListener

Parameters

Returns string

Parameters

Returns string

areSignalsBlocked

Returns boolean

blockSignals

Parameters

Returns void

createCutPlane

Parameters

Returns number

createCutPlaneFromEquation

Parameters

Returns number

createCutPlaneManipulator

Returns CutPlaneManipulatorInterface

See

fromJSON

Parameters

Returns boolean

See

getCutPlaneEquation

Parameters

Returns boolean

getCutPlaneGeometry

Parameters

Returns boolean

getCutPlaneGroup

Parameters

Returns number

getCutPlanesCount

Returns number

getCutPlanesIds

Returns number[]

getMaxCutPlanesCount

Returns number

hasEventListener

Parameters

Returns boolean

hasEventListenerById

Parameters

Returns boolean

isCutPlaneEnabled

Parameters

Returns boolean

removeAllCutPlanes

Returns void

removeAllEventListeners

Returns boolean

removeCutPlane

Parameters

Returns boolean

removeEventListener

Parameters

Returns boolean

Parameters

Returns boolean

removeEventListenerById

Parameters

Returns boolean

setCutPlaneEnabled

Parameters

Returns boolean

setCutPlaneGroup

Parameters

Returns boolean

toJSON

Parameters

Returns Object

See

updateCutPlaneGeometry

Parameters