AlCloud

Synopsis

#include <AlCloud.h>
class AlCloud :	public AlObject
enum Subset
{
	kSubsetInside,
	kSubsetOutside,
	kSubsetBoth
};
AlCloud();
virtual	~AlCloud();
virtual AlObjectType	type() const;
virtual AlObject *	copyWrapper() const;
virtual statusCode	deleteObject();
statusCode	create();
virtual const char*	name() const;
virtual statusCode	setName( const char* );
boolean	visible();
statusCode	setVisibility( boolean );
statusCode	translation( double&, double&, double& );
statusCode	setTranslation( double, double, double );
statusCode	rotation( double&, double&, double& );
statusCode	setRotation( double, double, double );
statusCode	scale( double&, double&, double& );
statusCode	setScale( double, double, double );
statusCode	boundingBox( double&, double&, double&, double&, double&, double& );
statusCode	subset( Subset, AlCloud **, double, double, double, double, double, double );
statusCode	merge( AlCloud * );
int 	numberOfPoints() const;
statusCode	points( int, float[] );
statusCode	addPoints(double, double, double, double, double, double, int, float[] );
statusCode	pick();
statusCode	unpick();
boolean	isPicked();
AlCloud *	nextCloud() const;
statusCode	nextCloudD( AlCloud * ) const;

Description

The AlCloud API is the interface to clouds and their data. You can do operations on clouds of points such as: creating, naming, picking, or merging them; controlling their visibility; setting their transformations; subsetting a cloud of points; or adding points to an existing cloud. You can also access most cloud settings, such as the current translation, scale or pick state.

You can also:

Retrieve the number of points in a cloud with the numberOfPoints() method
Retrieve the actual points with the points() method
Add points with the addPoints() method. (See the descriptions below for information on how to set up the data structures for these methods.)
Import a cloud of points with the method AlUniverse::importCloudFile()
Walk a cloud list with AlUniverse::firstCloud() in conjunction with AlCloud::nextCloud(). (Use AlUniverse::applyIteratorToClouds() to walk all cloud elements.)

See the descriptions below for information on how to set up the data structures for these methods.

NoteClouds are not in the Alias DAG tree.

A cloud will not be an item on the Alias pick list. (You must use AlCloud pick methods rather than AlPickList methods.)

To add arbitrary points to a cloud, you must create a cloud with the new points and then merge it into the cloud that you want to expand. The new cloud is deleted once it is merged. The new extended cloud has the outer bounding box of the two clouds.

AlUniverse::importCloudFile() has a parameter which controls the sampling factor when the cloud file is imported.

AlCloud::AlCloud()

Description

Constructs an AlCloud wrapper object.

AlCloud::~AlCloud()

Description

Deletes an AlCloud wrapper object.

statusCode AlCloud::deleteObject()

Description

Deletes the cloud object.

Return Codes

sSuccess - the method succeeded

sFailure - the method failed

sInvalidObject - the object was invalid

AlObject *AlCloud::copyWrapper() const

Description

Returns an exact copy of the cloud wrapper.

statusCode AlCloud::create()

Description

Creates a cloud object. The cloud will have no points and the minimum and maximum points of its bounding box will all be zero.

Return Codes

sSuccess - the cloud was created

sFailure - the cloud could not be created or the cloud object is already valid

AlObjectType AlCloud::type() const

Description

Returns the class identifier kCloudType.

const char *AlCloud::name() const

Description

Returns the name of the cloud object.

statusCode AlCloud::setName( const char *cloudName )

Description

Changes the name of a cloud. If the name is not unique then a new name is generated and a status of sNameChangedToUniqueOne is returned.

Arguments

< cloudName - new name of the object

Return Codes

sSuccess - the name was changed

sInvalidArgument - the cloudName was NULL

sFailure - the request could not be completed

sInvalidObject - the cloud was invalid

sNameChangedToUniqueOne - the name was changed to a unique version of the given name

boolean AlCloud::visible()

Description

Returns TRUE if the cloud is visible.

statusCode AlCloud::setVisibility( boolean on_or_off )

Description

Sets the visibility of the cloud according to the boolean on_or_off parameter.

Note: if this cloud is currently picked, it is unpicked so that pick list operations will not affect the cloud while it is invisible. When made visible again, the cloud will be unpicked.

Arguments

< on_or_off - either TRUE or FALSE

Return Codes

sSuccess - the method was able to set the visibility

sFailure - the method failed

sInvalidObject - the cloud is invalid

statusCode AlCloud::translation( double &x, double &y, double &z )

Description

Returns the current translation of the cloud of points. The returned translation is in world space.

Arguments

> x - the cloud’s x translation

> y - the cloud’s y translation

> z - the cloud’s z translation

Return Codes

sSuccess - the translation was found

sFailure - the method failed

sInvalidObject - the cloud is invalid

statusCode AlCloud::setTranslation( double x, double y, double z )

Description

Sets the translation of the cloud of points. The translation is in world space coordinates.

Arguments

< x - x translation to be set

< y - y translation to be set

< z - z translation to be set

Return Codes

sSuccess - the translation of the cloud was set

sFailure - the method failed

sInvalidObject - the cloud is invalid

statusCode AlCloud::rotation( double &x, double &y, double &z )

Description

Returns the current rotation of the cloud of points. The rotation returned is in world space coordinates.

Arguments

> x - cloud’s x rotation

> y - cloud’s y rotation

> z - cloud’s z rotation

Return Codes

sSuccess - the rotation was found

sFailure - the method failed

sInvalidObject - the cloud is invalid

statusCode AlCloud::setRotation( double x, double y, double z )

Description

Sets the rotation of the cloud of points. The rotation is in world space coordinates.

Arguments

< x - x rotation to be set

< y - y rotation to be set

< z - z rotation to be set

Return Codes

sSuccess - the rotation of the cloud was set

sFailure - the method failed

sInvalidObject - the cloud is invalid

statusCode AlCloud::scale( double &x, double &y, double &z )

Description

Returns the current scale of the cloud of points. The scale returned is in world space coordinates.

Arguments

> x - cloud’s x scale

> y - cloud’s y scale

> z - cloud’s z scale

Return Codes

sSuccess - the scale was found

sFailure - the method failed

sInvalidObject - the cloud is invalid

statusCode AlCloud::setScale( double x, double y, double z )

Description

Sets the scale value of the cloud of points. The scale is in world space coordinates.

Arguments

< x - x scale to be set

< y - y scale to be set

< z - z scale to be set

Return Codes

sSuccess - the scale of the cloud was set

sFailure - the method failed

sInvalidObject - the cloud is invalid

statusCode AlCloud::boundingBox( double &minX, double &minY, double &minZ, double &maxX, double &maxY, double &maxZ )

Description

Returns the bounding box of the cloud of points. The bounding box corners are determined by combinations of the min and max values: (minX,minY,minZ), (minX,minY,maxZ), (minX,maxY,minZ), (minX,maxY,minZ) and so on.

Arguments

> minX - minimum x value of the cloud

> minY - minimum y value of the cloud

> minZ - minimum z value of the cloud

> maxX - maximum x value of the cloud

> maxY - maximum y value of the cloud

> maxZ - maximum z value of the cloud

Return Codes

sSuccess - the bounding box was found

sFailure - the method failed

sInvalidObject - the cloud was invalid

statusCode AlCloud::subset( Subset partToKeep, AlCloud **newCloud, double minX, double minY, double minZ, double maxX, double maxY, double maxZ )

Description

Subsets a cloud of points based on which part to keep and the bounding box min and max value parameters. When both parts of the subsetted cloud are kept, the part outside the bounding box is returned as the newCloud variable. newCloud may be NULL.

Note: calling subset(kSubsetBoth, ... ) has side effects on the cloud link list that is retrieved from the AlUniverse class. This same link list is also used by the AlUniverse::applyIteratorsToClouds() method. In the kSubsetBoth case, when the method is successfully completed the original cloud is deleted and two new clouds are created. Note that when you walk the cloud list yourself or use an iterator, your code will fail if it tries to advance from the cloud that was just deleted.

If this method fails, it may be the case that the cloud was deleted.

Arguments

< partToKeep - one of kSubsetInside, kSubsetOutside or kSubsetBoth

> newCloud - cloud created outside of the bounding box when kSubsetBoth is used; could be a NULL parameter

< minX - minimum x of cloud subset bounding box

< minY - minimum y of cloud subset bounding box

< minZ - minimum z of cloud subset bounding box

< maxX - maximum x of cloud subset bounding box

< maxY - maximum y of cloud subset bounding box

< maxZ - maximum z of cloud subset bounding box

Return Codes

sSuccess - the cloud was subsetted successfully

sInvalidArgument - invalid bounding box minimum and maximum parameters

sFailure - the method failed

sInvalidObject - the cloud is invalid

statusCode AlCloud::merge( AlCloud *cloudToMerge )

Description

Merges a valid cloud into the current cloud. cloudToMerge is deleted and its wrapper is invalidated after the successful completion of this method. The resulting cloud takes on the outer extents of itself and the cloud that was merged.

Arguments

< cloudToMerge - cloud to be merged

Return Codes

sSuccess - the merge was successful

sInvalidArgument - the cloud to be merged was invalid, or the two clouds to be merged were the same

sFailure - the method failed

sInvalidObject - this cloud is invalid

int AlCloud::numberOfPoints() const

Description

Returns the number of points that are in the cloud. A negative number is returned if there is an error or if the cloud is invalid. This routine is used in conjunction with AlCloud::points() so that you know how much storage to allocate for the points array.

statusCode AlCloud::points(int numberOfPoints, float pointArray[] )

Description

Provides access to the list of points within a cloud. Because a point consists of 3 floats, a cloud with 10 points would require a pointArray of size 30 to retrieve all points of the cloud. To access the points within the array, use the following code:

Example code:  int num = cloud->numberOfPoints(); float *points = (float *) malloc( sizeof(float) * num * 3 );       if ( points == NULL )           	return;       if ( cloud->points( num, points ) != sSuccess )           	return;       float *pt = points;       for ( int i = 0 ; i < num ; i++ )       {           	pt[0] += x; pt[1] += y; pt[2] += z; pt += 3;       }

Note: numberOfPoints can be less than the actual number of points. The method will place as many points as possible into the array and then return successfully.

Arguments

< numberOfPoints - size of the pointArray. Must be a value greater than 0 for every n points; you need to allocate n * 3 elements

> pointArray - array in which to return points

Return Codes

sSuccess - the method succeeded

sInvalidArgument - the method failed. numberOfPoints is less than 1 or pointArray is NULL

sFailure - the method failed

sInvalidObject - the cloud is invalid

statusCode AlCloud::addPoints( double minX, double minY, double minZ, double maxX, double maxY, double maxZ, int numberOfPoints, float points[] )

Description

Adds points within a min and max bounding box to a cloud. This method only works on a cloud that has no points and extents of zero. Any point in the points[ ] array outside of the specified min and max extents is skipped.

Note: as in the points() method, the points parameter is a float[ 3 * numberOfPoints ] array.

Arguments

< minX - minimum x of cloud bounding box

< minY - minimum y of cloud bounding box

< minZ - minimum z of cloud bounding box

< maxX - maximum x of cloud bounding box

< maxY - maximum y of cloud bounding box

< maxZ - maximum z of cloud bounding box

< numberOfPoints - number of points in the point array. Each point is 3 doubles. (This is not the same as array size.)

< points - the point array

Return Codes

sSuccess - the points were successfully added to the cloud

sInvalidArgument - invalid bounding box

sFailure - the current cloud does not have zero extents and no points, or the method failed

sInvalidObject - the cloud is invalid

statusCode AlCloud::pick()

Description

Picks the cloud of points.

Return Codes

sSuccess - the pick worked

sFailure - the method failed

sInvalidObject - the cloud is invalid

statusCode AlCloud::unpick()

Description

Unpicks the cloud of points.

Return Codes

sSuccess - the unpick worked

sFailure - the method failed

sInvalidObject - the cloud is invalid

boolean AlCloud::isPicked()

Description

Returns TRUE if the cloud is picked.

AlCloud *AlCloud::nextCloud() const

Description

Returns the next cloud in the universe.

statusCode AlCloud::nextCloudD( AlCloud *currentCloud ) const

Description

A destructive method for moving to the next cloud. sFailure is returned if there is no next cloud.

Arguments

< currentCloud - the cloud to obtain the next cloud from

Return Codes

sSuccess - the method succeeded

sFailure - the method failed or there is no next cloud in the list

sInvalidObject - the cloud is invalid