3Delight 8.5 User's Manual: 9.7 The Point Cloud API

Short Contents

9.7 The Point Cloud API

An easy to use C++ API is provided with 3Delight to read and write point cloud files as those generated by the bake3d() shadeop. To use the API, one has to include the `pointcloud.h' header file that is distributed in the package and link the application with the 3Delight library (see section Linking with 3Delight).

9.7.1 Point Cloud API Data Types

Only one type is defined in `pointcloud.h'

typedef void * PtcPointCloud

This typedef is used as a handle to a point cloud file on disk.

9.7.2 Point Cloud Reading

PtcPointCloud PtcOpenPointCloudFile ( const char *filename, int *nvars, const char **vartypes, const char **varnames )

This function opens a given file for reading and returns a file handle than shall be used in other reading calls.

filename: The complete path to the point cloud file
nvars: A pointer to an int that will be filled with the total number of channels in the point cloud file.
varnames: A pointer to an array of const char * that will hold the name of each variable.
vartypes: A pointer to an array of const char * that will hold the type of each variable. Types are string representing the type of the variable as declared in the shading language (color, point, float, normal, … etc).

This function could fail if the file is not accessible or is not a valid point cloud file, in which case null is returned.

NOTE
This API call is badly designed since the caller cannot know the size of vartypes and varnames in advance. But for compatibly reasons with other software we decided to stick with this API. A simple and secure workaround goes as follows:

Call PtcOpenPointCloudFile with vartypes and varnames set to null to obtain nvars.
Close the returned file handle.
Allocate arrays big enough for vartypes and varnames since now we know their size.
Call PtcOpenPointCloudFile again with the allocated arrays.

int PtcGetPointCloudInfo ( PtcPointCloud pointcloud, const char *request, void *result )

This function returns informations about a point cloud file. Accepted requests are:

pointcloud

A handle to the point cloud file as returned by PtcOpenPointCloudFile

request

The name of the information needed. The following requests are accepted:

` npoints': Number of points in the point cloud file. C++ data type is int
` bbox': The bounding box of the point cloud. Will return an array of six floats: min x, min y, min z, max x, max y and max z.
` datasize': The number of floats needed to store each data point. C++ data type is int.
` world2eye': The world to eye (world to camera) transformation matrix. Will return an array of 16 floats.
` world2ndc': The world to NDC transformation matrix. Will return an array of 16 floats.
` format': The resolution of the render that generated the point cloud file. Three floats will be returned: x resolution, y resolution and aspect ratio.

result

A pointer to an array large enough to hold the returned informations.

Returns 1 if the request is successful, 0 otherwise.

NOTE
Some point cloud files generated with older 3Delight versions may not contain the `format' information.

int PtcReadDataPoint ( PtcPointCloud pointcloud, float *point, float *normal, float *radius, float *user_data )

Reads next point from the point cloud file. The parameters are:

pointcloud: The handle to the point cloud file as returned by PtcOpenPointCloudFile.
point: A pointer to a point (three floats) that will be filled with current point's position.
normal: A pointer to a point (three floats) that will be filled with current point's normal.
radius: A pointer to float that will be filled with point's radius. The area of the micro-polygon that generated this sample is radius * radius * 4.
user_data: A pointer to a user buffer of a size big enough to hold all the variables attached to a point. The size of the buffer, in floats, can be obtained by calling PtcGetPointCloudInfo with request set to `datasize'.

Returns 1 if the operation is successful, 0 otherwise.

NOTE
point, normal, radius and user_data can be null if their value is not neede.

void PtcClosePointCloudFile ( PtcPointCloud pointcloud ): Closes a file opened with PtcOpenPointCloudFile.

9.7.3 Point Cloud Writing

PtcPointCloud PtcCreatePointCloudFile ( const char *filename, int nvars, const char **vartypes, const char **varnames, float *world2eye, float *world2ndc, float *format)

Creates the specified point cloud file. If the point cloud file already exists, it will be overwritten.

filename: Complete path to point cloud file.
nvars: Number of variables to save in the point cloud.
vartype: A type for each variable. Types are the same as in the shading language: point, normal, color, float, matrix ... Etc.
varname: A name for each variable.
world2eye: A world to camera transformation matrix.
world2ndc: A world to NDC transformation matrix.
format: The X resolution, Y resolution and aspect ratio of the image.

int PtcWriteDataPoint ( PtcPointCloud pointcloud, float *point, float *normal, float radius, float *data)

Adds a point, along with its data, to a point cloud file.

pointcloud: A handle to a point cloud file as returned by PtcCreatePointCloudFile.
point
normal
radius: Position, orientation and radius of the point and data. point and normal cannot be null.
data: Array of floats containing data for all variables, continuously in memory. The data must be of the same size as the sum of sizes of the variables passed to PtcCreatePointCloudFile.

Returns 1 if the operation is successful, 0 otherwise.

void PtcFinishPointCloudFile ( PtcPointCloud pointcloud): Writes out all data to disk and closes the file.

9.7.4 API Example

An example is available in `$DELIGHT/examples/ptc2rib' directory. This simple application transforms a point cloud file into a RIB that is renderable using renderdl. An example usage is:

ptc2rib cloud.ptc | renderdl -d

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]