Working with Point Cloud Entities

Point cloud entities work together with point cloud definition objects to represent point clouds inside a drawing. The relationship between these two kinds of objects is very similar to the relationship between a block definition and block reference objects or between a raster image definition and raster image entity objects.

A point cloud entity is a selectable, drawable entity that places a point cloud in model or paper space inside the drawing. The point cloud entity is linked to exactly one point cloud definition object, and two or more entities can be linked to a single definition object.

A point cloud entity contains a set of parameters such as clip boundary, intensity, etc., and general OdDbEntity properties such as color and layer.

Point cloud entities are represented by the OdDbPointCloud class.

Creating a point cloud entity

To create a point cloud entity, declare an object of OdDbPointCloudPtr class (which is the specialization of the OdSmartPtr class for OdDbPointCloud pointers), and use the createObject() method of the OdDbPointCloud class that is the static pseudo-constructor. For example:


OdDbPointCloudPtr pPointCloud = OdDbPointCloud::createObject();

An OdDbPointCloud object cannot be used by itself; it must be linked to the specific point cloud definition object that contains all information about the external point cloud file. The following method sets the Object ID of the OdDbPointCloudDef object associated with the entity:


void setPointCloudDefId(const OdDbObjectId);

For getting an Object ID of the associated point cloud, the pointCloudDefId() method is used. For example:


if(pPointCloud->pointCloudDefId() == OdDb::kNull)
   pPointCloud->setPointCloudDefId(pointCloudDefId);

Also for creating a point cloud entity, you can use the ::oddbCreatePointCloudEntity() method:


OdResult oddbCreatePointCloudEntity(OdDbBlockTableRecord* pBlockToAdd, OdDbPointCloudPtr& newPointCloud, const OdString& indexFile, const OdString& sourceFile, const OdGePoint3d& location = OdGePoint3d::kOrigin, double scale = 1.0, double rotation = 0.0, const OdGeVector3d& vAxis = OdGeVector3d::kZAxis);

The method not only creates the OdDbPointCloud entity, but also creates the OdDbPointCloudDef if needed (or finds the existing proper one) and restores or creates new links to the OdDbPointCloudDef object, applies specified attributes, and adds reactors. For an example of usage, see Inserting a Point Cloud into a Drawing.

Working with properties of point cloud entities

Besides the general entity properties (color, layer, etc.), the OdDbPointCloud class supports specific point cloud properties such as: source file name, intensity, and so on, and provides a set of methods for working with them.

The name of the file that contains the point cloud data can be set by the point cloud entity (not only by the corresponding definition object) using the setSourceFileName() method:


bool setSourceFileName(const OdString&);

To get the actual source file name, use the getSourceFileName() method:


bool getSourceFileName(OdString &) const;

The following methods provide an interface for working with point cloud intensity:

OdResult setIntensityScheme(const int); — Sets an intensity scheme by its index:
- ISCHEME_GRAYSCALE = 0,
- ISCHEME_SPECTRUM = 1,
- ISCHEME_SINGLE_RED = 2,
- ISCHEME_SINGLE_GREEN = 3,
- ISCHEME_SINGLE_BLUE = 4
int getIntensityScheme() const; — Returns the index of the current intensity scheme.
OdResult setShowIntensity(const bool); — Sets the boolean value that enables or disables the display of intensity.
bool showIntensity() const; — Returns whether display of intensity is enabled.

Transforming point cloud entities

As any OdDbEntity object, an OdDbPointCloud instance can be transformed by translating, rotating, scaling or by a combination of these operations. The setTransformation() method transforms the entity by applying the specified transformation matrix to the entity:


OdResult OdDbPointCloud::setTransformation(const OdGeMatrix3d& transformation)

The matrix must be uniscaled and orthogonal.

For example, a newly created point cloud entity has a location at (0,0,0) and to set a new location, define a translation matrix and pass it to the setTransformation() method as an argument:


OdGeMatrix3d translateMatrix;
translateMatrix.setToTranslation(location.asVector());
pointCloud->setTransformation(translateMatrix);

The current transformation matrix can be obtained using the transformation() method:


OdGeMatrix3d transformation() const;

Working with clipping boundaries

Point cloud entities support clipping. A single definition object can be linked with two or more entities; each of them can have its own clipping boundaries and this is the efficient way to display different parts of the point cloud object in the drawing.

Clipping boundaries are represented by the OdDbPointCloudClipping class. To create an empty clipping boundary object, use the constructor:


OdDbPointCloudClipping();

There are two available types of point cloud clipping boundaries: rectangle (or box in 3D space) and polygonal. To set the boundary to the desired type, use the proper method:

void setBox(OdGePoint3d const &, OdGePoint3d const &);
void setRectangle(OdGePoint2d const &, OdGePoint2d const &);
void setBoundary(OdArray const &);

The methods specify the created clipping boundary object to the specific type of boundary with an array of vertices. The first two methods set a rectangle (box) boundary by two vertices, and the third method sets a polygonal boundary clipping made of a vertices array (the last point must be identical to the first point).

The type() method returns the type of the boundary; available types are defined by the ClipType enumeration:

CT_BOX = 1
CT_RECTANGLE = 2
CT_POLYLINE = 3

The setType() method sets the specific type for the clipping boundary; the type must match the shape of the boundary points:


void setType(const ClipType);

Any point cloud entity can have more than one clipping boundary, and the resulting clipping is a combination of all clipping boundaries:

For supporting a number of clipping boundaries, OdDbPointCloud contains an array of OdDbPointCloudClipping objects, which is an efficient way to get, add, or remove particular boundaries. There is a set of methods that processes the array of clipping boundaries:

int clippingCount() const; — Returns the number of clipping boundaries (the size of the clipping boundaries array) for this point cloud entity.
bool addClippingBoundary(OdDbPointCloudClipping const &); — Adds a clipping boundary to the clipping boundaries array.
bool removeClippingBoundary(int); — Removes a clipping boundary item at the specified position from the clipping boundaries array.
void resetClippingBoundary(); — Resets all clipping boundaries.
OdDbPointCloudClipping const* getConstPointCloudClipping(int) const; — Returns a pointer to a constant PointCloudClipping object at the specified position in the clipping boundaries array.
OdDbPointCloudClipping* getPointCloudClipping(int); — Returns a pointer to a PointCloudClipping object at the specified position in the clipping boundaries array.

The following methods are used to define if the point cloud entity is displayed clipped or not.

OdResult setShowClipping(const bool); — Sets the boolean value that defines if the point cloud entity is to be displayed clipped.
bool showClipping() const; — Returns whether the point cloud entity is shown clipped.

Visibility of clipping boundaries is defined by the POINTCLOUDCLIPFRAME variable stored in drawing.

The following code fragment creates two rectangular clipping boundaries for the point cloud entity and enables clipping visibility:


OdDbPointCloudClipping clip1 = OdDbPointCloudClipping();
clip1.setRectangle(OdGePoint2d(-16,-7), OdGePoint2d(-1,6));

OdDbPointCloudClipping clip2 = OdDbPointCloudClipping();
clip2.setRectangle(OdGePoint2d(-8,-7), OdGePoint2d(-1,-1.5));
  
pPointCloud->addClippingBoundary(clip1);
pPointCloud->addClippingBoundary(clip2);

pPointCloud->setShowClipping(true);

Creating a point cloud entity

Working with properties of point cloud entities

Transforming point cloud entities

Working with clipping boundaries

See also: