SPApoint_cloud Class Reference
[Point Cloud]

This is the central class in ACIS Point Cloud Functionality. More...

#include <point_cloud.hxx>

Inheritance diagram for SPApoint_cloud:

[legend]

Collaboration diagram for SPApoint_cloud:

[legend]

List of all members.

Public Member Functions
int	add (double x, double y, double z)
	Adds a position to the point cloud.
int	add (SPAposition const &pos)
	Adds a position to the point cloud.
int	backup (const char *name=NULL)
	Records the state of the SPApoint_cloud object and returns the state identifier.
int	backup_id () const
	Returns the state ID of current state of the SPApoint_cloud object.
logical	backup_invalid () const
	Returns TRUE if the current state is invalid, otherwise FALSE.
const char *	backup_name () const
	Returns the name of current state of the SPApoint_cloud object.
logical	backup_state () const
	Returns TRUE if the current state has been rolled back, otherwise FALSE.
SPAbox	bound (logical force_recalc=FALSE)
	Returns the bounding box of the point cloud.
logical	compact (logical deep_compact=FALSE)
	Compacts the point cloud (expert interface).
SPApoint_cloud *	copy (logical deep_copy=FALSE)
	Creates a copy of the point cloud in either the simple copy or deep copy mode.
logical	delete_all_states ()
	Deletes all states owned by the SPApoint_cloud object.
logical	get (int index, SPAposition &pos, int &pos_list_index)
	Gets the position and the position list index at the given point cloud index (expert interface).
logical	get (int index, SPAposition &pos)
	Gets the position in a point cloud at the given point cloud index.
const SPApoint_cloud_custom_data *	get_custom_data () const
	Method that retrieves the SPApoint_cloud_custom_data object that this SPApoint_cloud object refers to.
virtual const SPAtransf *	get_transform () const
	Returns a pointer to the SPAtransf transform object associated with the point cloud.
logical	intersect (SPApoint_cloud &point_cloud)
	Performs an in-place boolean intersection between two point clouds.
void	invalidate_forward_states ()
	Invalidates all forward states owned by the SPApoint_cloud object.
int	max_index ()
	Gets the maximum point cloud index.
logical	modify (int index, double x, double y, double z)
	Modifies an existing position in the point cloud at the given point cloud index (expert interface).
logical	modify (int index, SPAposition const &pos)
	Modifies an existing position in the point cloud at the given point cloud index (expert interface).
logical	prune (int state_id)
	Deletes the state specified by the identifier.
logical	remove (int index)
	Removes a point from the point cloud at the given point cloud index.
int	roll (int steps=-1)
	Reactivates the state reached by rolling the specified number of steps through the known states.
int	roll_to (int state_id)
	Reactivates the state specified by the identifier returned from backup.
void	set_custom_data (SPApoint_cloud_custom_data *custom_data)
	Method that sets the SPApoint_cloud_custom_data on this SPApoint_cloud object.
int	size ()
	Gets the size of the point cloud.
	SPApoint_cloud (SPApoint_cloud_options *pc_opts=NULL, position_list_stream *pos_list=NULL)
	C++ allocation constructor requests memory for this object and populates it.
SPApoint_cloud *	subset (sortable_integer_ls *pos_list_indices, SPApoint_cloud_options *pc_opts=NULL)
	Creates a subset of the point cloud (expert interface).
SPApoint_cloud *	subset (integer_list_stream &indices, SPApoint_cloud_options *pc_opts=NULL)
	Creates a subset of the point cloud.
logical	subtract (SPApoint_cloud &point_cloud)
	Performs an in-place boolean subtraction of a point cloud from the current cloud.
logical	unite (SPApoint_cloud &point_cloud)
	Performs an in-place boolean unite operation on two point clouds.
virtual	~SPApoint_cloud ()
	Virtual C++ destructor, deleting a SPApoint_cloud object.
Protected Member Functions
virtual SPApoint_cloud *	make_object (SPApoint_cloud *target_pc, SPApoint_cloud_options *pc_opts, position_list_stream *pos_list, SPApoint_cloud_copy_type copy_type)
	You have to implement the make_object virtual method if you derived a class from SPApoint_cloud.

---

Detailed Description

This is the central class in ACIS Point Cloud Functionality.

Role: The SPApoint_cloud class is designed to hold large sets of points. This class provides functionality for the efficient storage and manipulation of large sets of points.

See also:
Point_Cloud Technical Article

---

Constructor & Destructor Documentation

SPApoint_cloud::SPApoint_cloud	(	SPApoint_cloud_options *	pc_opts = NULL,
		position_list_stream *	pos_list = NULL
	)

C++ allocation constructor requests memory for this object and populates it.

Role: Constructs a SPApoint_cloud object using the optional input arguments. Note: The point cloud takes ownership of the pos_list, if one is passed in.

Parameters:

	pc_opts	optional SPApoint_cloud_options specifying the properties of the constructed SPApoint_cloud object.
	pos_list	optional position_list_stream object containing initial points used in the SPApoint_cloud object. See also: Point_Cloud Technical Article

virtual SPApoint_cloud::~SPApoint_cloud

(

)

[virtual]

Virtual C++ destructor, deleting a SPApoint_cloud object.

Role: C++ destructor that is invoked on deletion of this object. Allocated memory is freed in this method. This method is declared virtual so you implement a destructor for your derived class.

See also:
Point_Cloud Technical Article

---

Member Function Documentation

int SPApoint_cloud::add	(	double	x,
		double	y,
		double	z
	)

Adds a position to the point cloud.

Role: This method enables addition of a single position to the point cloud. It returns the point cloud index at which the position is added.

Parameters:

	x	x coordinate of the SPAposition to add
	y	y coordinate of the SPAposition to add
	z	z coordinate of the SPAposition to add See also: Point_Cloud Technical Article

int SPApoint_cloud::add

(

SPAposition const &

pos

)

Adds a position to the point cloud.

Role: This method enables addition of a single position to the point cloud. It returns the point cloud index at which the position is added.

Parameters:

pos

SPAposition to add See also: Point_Cloud Technical Article

int SPApoint_cloud::backup

(

const char *

name = NULL

)

Records the state of the SPApoint_cloud object and returns the state identifier.

Role: This method creates a backup record that contains the current state of the point cloud and adds it to the list of known states. All forward states (that is, redo states) are removed and the new state becomes the last known state. Backup accepts and stores a pointer to a string that can be used as another means to identify a state. ACIS does not copy, modify, or assume ownership of this string in any way. It is up to you to create and destroy it appropriately. The return value is the identifier assigned to the new state. The identifier is a sequental number that is the quasi index of the state in the linked list of states. When assigned, it is the value of the earlier state plus one.

Parameters:

name

A custom name for the state. See also: Point_Cloud Technical Article

int SPApoint_cloud::backup_id

(

)

const

Returns the state ID of current state of the SPApoint_cloud object.

Note: The return value is -1 if no states exist.

See also:
Point_Cloud Technical Article

logical SPApoint_cloud::backup_invalid

(

)

const

Returns TRUE if the current state is invalid, otherwise FALSE.

Note: The return value has no meaning if no states exist.

See also:
Point_Cloud Technical Article

const char* SPApoint_cloud::backup_name

(

)

const

Returns the name of current state of the SPApoint_cloud object.

Note: The return value is NULL if no states exist.

See also:
Point_Cloud Technical Article

logical SPApoint_cloud::backup_state

(

)

const

Returns TRUE if the current state has been rolled back, otherwise FALSE.

Note: The return value has no meaning if no states exist.

See also:
Point_Cloud Technical Article

SPAbox SPApoint_cloud::bound

(

logical

force_recalc = FALSE

)

Returns the bounding box of the point cloud.

Role: The bound method returns the box bounding all points in the cloud. The call to bound will trigger a re-calculation of the bounding box only if the bounding box is obsolete. Optionally, you can force a recalculation of the bounding box.

Parameters:

force_recalc

Force a recalculation of the bounding box. The default value is FALSE. See also: Point_Cloud Technical Article

logical SPApoint_cloud::compact

(

logical

deep_compact = FALSE

)

Compacts the point cloud (expert interface).

Role: The compact method does multiple things to the point cloud that cannot be undone, so you must use this functionality with care. This method will delete all the backups of prior states of the point cloud and will invalidate all iterators associated with the cloud. In the default case that the flag deep_compact is FALSE, the point cloud is re-indexed to eliminate any indices for points that have been removed from the cloud. If the flag is set to TRUE, the point cloud positions are unshared from all other point clouds, and only the positions relevant to the current cloud are retained.
Note: The results of point cloud compaction are permanent, and compacting the position list has ramfications for other operations such as the boolean operations.

Parameters:

deep_compact

Optional argument that causes the positions to be unshared from other point clouds and irrelevant points to be permanently deleted from the cloud. See also: Point_Cloud Technical Article

SPApoint_cloud* SPApoint_cloud::copy

(

logical

deep_copy = FALSE

)

Creates a copy of the point cloud in either the simple copy or deep copy mode.

Role: This copy method makes a simple or deep copy of this point cloud depending on the value of the input. The simple copy results in a point cloud which shares the positions with the original cloud, whereas the deep copy leads to a point cloud which copies all the position data the new cloud.
Note: Deep copying a point cloud has implication for some operations such as the boolean operations.

Parameters:

deep_copy

Determines whether to make a simple or a deep copy. The default is FALSE. See also: Point_Cloud Technical Article

logical SPApoint_cloud::delete_all_states

(

)

Deletes all states owned by the SPApoint_cloud object.

Role: Use this method method to permanently delete all backup records. Returns FALSE if no states exist.

See also:
Point_Cloud Technical Article

logical SPApoint_cloud::get	(	int	index,
		SPAposition &	pos,
		int &	pos_list_index
	)

Gets the position and the position list index at the given point cloud index (expert interface).

Role: The expert interface get method retrieves the SPAposition at the given point cloud given index as well as the index in the position list. The method returns FALSE if the point cloud index is not valid.
Note: You should always check the return value of the call, because the retrieved position may not be usable if the method returns FALSE.

Parameters:

	index	The point cloud index of the desired position.
	pos	The position retrieved from the point cloud.
	pos_list_index	The position list index associated with the retrieved position. See also: Point_Cloud Technical Article

logical SPApoint_cloud::get	(	int	index,
		SPAposition &	pos
	)

Gets the position in a point cloud at the given point cloud index.

Role: The get method retrieves the SPAposition at the given point cloud index. The method returns FALSE if the index is not valid.
Note: You should always check the return value of the call, because the retrieved position may not be usable if the method returns FALSE.

Parameters:

	index	The point cloud index of the desired position.
	pos	The position retrieved from the point cloud. See also: Point_Cloud Technical Article

const SPApoint_cloud_custom_data* SPApoint_cloud::get_custom_data

(

)

const

Method that retrieves the SPApoint_cloud_custom_data object that this SPApoint_cloud object refers to.

The SPApoint_cloud class maintains a reference to an instance of the SPApoint_cloud_custom_data class. If you want to store custom information with the point-cloud, you can choose to derive your application-specific class from SPApoint_cloud_custom_data.

See also:
Point_Cloud Technical Article

virtual const SPAtransf* SPApoint_cloud::get_transform

(

)

const [virtual]

Returns a pointer to the SPAtransf transform object associated with the point cloud.

Role: The get_transform method is used by ACIS functions to query for the transform associated with the point cloud. This method is defined as a virtual method to allow you to define the transform for your class derived from SPApoint_cloud. The default base class implementation of this method returns a pointer to a global identity transform.

See also:
Point_Cloud Technical Article

logical SPApoint_cloud::intersect

(

SPApoint_cloud &

point_cloud

)

Performs an in-place boolean intersection between two point clouds.

Role: The boolean intersection method retains the points common to both clouds. The results replaces the current point cloud. This method works only if the input and the current point clouds share the positions and have the same transform. Otherwise, this method returns FALSE.

Parameters:

point_cloud

Note: This operation will invalidate any iterators associated with the current cloud. The point cloud whose points are to be intersected with the current cloud. See also: Point_Cloud Technical Article

void SPApoint_cloud::invalidate_forward_states

(

)

Invalidates all forward states owned by the SPApoint_cloud object.

Role: Use this method to invalidate all backup records that have been undone. The main purpose for this is to assure that forward states cannot be reinstated after the SPApoint_cloud object has been modified. Otherwise it would be possible to roll to an earlier state, then modify the point cloud, then roll to a later state (forward), which will result in unexpected behavior. This method is automatically called by all base class methods that modify the point cloud. Call this method in derived class methods as needed.

See also:
Point_Cloud Technical Article

virtual SPApoint_cloud* SPApoint_cloud::make_object	(	SPApoint_cloud *	target_pc,
		SPApoint_cloud_options *	pc_opts,
		position_list_stream *	pos_list,
		SPApoint_cloud_copy_type	copy_type
	)			[protected, virtual]

You have to implement the make_object virtual method if you derived a class from SPApoint_cloud.

See also:
Point_Cloud Technical Article

int SPApoint_cloud::max_index

(

)

Gets the maximum point cloud index.

Role: The max_index method returns the maximum point cloud index. If points have been deleted from the cloud, the returned value will be larger than the size of the point cloud. This method returns -1 if the point cloud is empty.

See also:
Point_Cloud Technical Article

logical SPApoint_cloud::modify	(	int	index,
		double	x,
		double	y,
		double	z
	)

Modifies an existing position in the point cloud at the given point cloud index (expert interface).

Role: Modifies the point in the point cloud corresponding to the given point cloud index. The method returns FALSE if the index is invalid or the operation is otherwise unsuccessful.
Note: The modify call works only if the positions are not shared with any other SPApoint_cloud object or by the history mechanism of the point cloud.

Parameters:

	index	The point cloud index.
	x	x coordinate of the SPAposition to modify.
	y	y coordinate of the SPAposition to modify.
	z	z coordinate of the SPAposition to modify. See also: Point_Cloud Technical Article

logical SPApoint_cloud::modify	(	int	index,
		SPAposition const &	pos
	)

Modifies an existing position in the point cloud at the given point cloud index (expert interface).

Role: Modifies the point in the point cloud corresponding to the given point cloud index. The method returns FALSE if the index is invalid or the operation is otherwise unsuccessful.
Note: The modify call works only if the positions are not shared with any other SPApoint_cloud object or by the history mechanism of the point cloud.

Parameters:

	index	The point cloud index.
	pos	The new value of the SPAposition at this index. See also: Point_Cloud Technical Article

logical SPApoint_cloud::prune

(

int

state_id

)

Deletes the state specified by the identifier.

Role: Use this method to permanently delete a specific state. Returns FALSE if the specified state does not exist.

Parameters:

state_id

The identifier of the state to delete. See also: Point_Cloud Technical Article

logical SPApoint_cloud::remove

(

int

index

)

Removes a point from the point cloud at the given point cloud index.

Role: Removes the point in the point cloud corresponding to the given point cloud index. The method returns FALSE if the index is not valid.

Parameters:

index

The index of the point to be removed from the SPApoint_cloud. See also: Point_Cloud Technical Article

int SPApoint_cloud::roll

(

int

steps = -1

)

Reactivates the state reached by rolling the specified number of steps through the known states.

Role: This is the primary means for undoing and reapplying backup records by "rolling" either forwards or backwards through the known states. Negative step values rusult in roll back, which is undo, and positive values result in roll forward, which is redo. The return value is the number of steps successfully rolled.

Parameters:

steps

The number of steps to roll through the states. See also: Point_Cloud Technical Article

int SPApoint_cloud::roll_to

(

int

state_id

)

Reactivates the state specified by the identifier returned from backup.

Role: This method will roll through backup records, either forwards or backwards, until it either reaches the specificed state or the state with the lowest state ID that is not less than the one specified. Rolling to state ID zero for example, will always result in rolling to the very first state. The return value is the number of steps successfully rolled.

Parameters:

state_id

The identifier of the state to reactivate. See also: Point_Cloud Technical Article

void SPApoint_cloud::set_custom_data

(

SPApoint_cloud_custom_data *

custom_data

)

Method that sets the SPApoint_cloud_custom_data on this SPApoint_cloud object.

The SPApoint_cloud class maintains a reference to an instance of the SPApoint_cloud_custom_data class. If you want to store custom information with the point-cloud, you can choose to derive your application-specific class from SPApoint_cloud_custom_data.

See also:
Point_Cloud Technical Article

int SPApoint_cloud::size

(

)

Gets the size of the point cloud.

Role: The size method returns the number of active points contained in the point cloud.

See also:
Point_Cloud Technical Article

SPApoint_cloud* SPApoint_cloud::subset	(	sortable_integer_ls *	pos_list_indices,
		SPApoint_cloud_options *	pc_opts = NULL
	)

Creates a subset of the point cloud (expert interface).

Role: The subset method creates a new point cloud that contains a subset of points from the original cloud. The new point cloud contains the points specified in terms of indices of the position list in the original cloud. The subset cloud inherits the option settings from the original point cloud if the options are left unspecified. The point cloud assumes ownership of the pos_list_indices object.
Note: This interface does not check to ensure that the position list indices are valid.

Parameters:

	indices	The indices of the points with respect to the position list.
	pc_opts	The point cloud options object. See also: Point_Cloud Technical Article

SPApoint_cloud* SPApoint_cloud::subset	(	integer_list_stream &	indices,
		SPApoint_cloud_options *	pc_opts = NULL
	)

Creates a subset of the point cloud.

Role: The subset method creates a new point cloud that contains a subset of points from the original cloud. The new point cloud contains the points specified in terms of the point cloud indices of the original cloud. The subset cloud inherits the option settings from the original point cloud if the options are left unspecified. The subset method returns NULL if the point cloud indices in the input are invalid.

Parameters:

	indices	The point cloud indices of points to include in the subset.
	pc_opts	The point cloud options object. See also: Point_Cloud Technical Article

logical SPApoint_cloud::subtract

(

SPApoint_cloud &

point_cloud

)

Performs an in-place boolean subtraction of a point cloud from the current cloud.

Role: The boolean subtract method removes the common points between the input and current point cloud from the current cloud. The result replaces the current point cloud. This method works only if the input and current point clouds share the positions and have the same transform. Otherwise, this method returns FALSE.
Note: This operation will invalidate any iterators associated with the current cloud.

Parameters:

point_cloud

The point cloud whose points are to be subtracted from the current cloud. See also: Point_Cloud Technical Article

logical SPApoint_cloud::unite

(

SPApoint_cloud &

point_cloud

)

Performs an in-place boolean unite operation on two point clouds.

Role: The boolean unite method combines the points of two point clouds into one cloud. If the positions are shared between the two clouds and the transforms are the same, then duplicate points are included only once in the result. Otherwise, the points in the input cloud are all added as new points to the current cloud (without checking for duplicates in 3D space). The result always replaces the current cloud. This method returns TRUE if the operation is successful.
Note: This operation will invalidate any iterators associated with the current cloud.

Parameters:

point_cloud

The point cloud whose points are to be united with the current cloud. See also: Point_Cloud Technical Article