/home/slemaign/softs-local/BioMove3D-git/collision/Kcd/kcd_api.c File Reference

This files contains API functions of KCD. More...

#include "Util-pkg.h"
#include "Collision-pkg.h"

Classes
struct	kcd_scene_data
Typedefs
typedef struct kcd_scene_data	kcd_scene_data
typedef struct kcd_scene_data *	kcd_scene_data_p
Functions
void	kcd_mo_moved (int kcd_obj_id, int is_moved)
	keeps track of status of a movable object since the latest call to KCD collision test
int	kcd_get_is_moved (int mo_id)
	returns whether or not the movable object must be tested for collision again (whether or not it moved more recently than the latest collision test)
int	kcd_is_initialized ()
	returns the value of kcd_initialized
int	kcd_get_nof_mos ()
	Get the number of movable objects known by KCD.
int	kcd_get_nof_grps ()
	Get the number of groups.
int	kcd_get_nof_sos ()
	Get the number of static objects.
void	deconnect_kcd_data ()
	Cleans up KCD and resets the data.
void	kcd_remember_scene (int kcd_scene_id)
	Select a scene with the kcd_scene_id.
void	kcd_beg_scene (int tot_nof_prims, int nof_st_obj, int nof_mo_grps, int nof_mov_obj)
	Initializes some internal KCD data structures.
int	kcd_end_scene ()
	builds remaining internal hierarchies necessary for KCD
void	kcd_clean_up ()
	free-s all memory of the internal data structures used by KCD
void	kcd_beg_obj (int can_move)
	adding an object
int	kcd_end_obj ()
	creates OBB-tree on all single OBBs and on all roots of OBB-trees of the primitives and polyhedrons in the object
int	kcd_add_prim (void *primPt)
	creates OBB's on the primitives
int	kcd_def_mo_grp (int *arr_kcd_ids, int nof_mo_ids)
	makes group of several given movable objects
void	kcd_def_mo_no_grp (void)
	makes a group (-1) with movable object without groups
void	kcd_act_mo (int mo_id)
	the given movable object is considered by the collision test
void	kcd_deact_mo (int mo_id)
	the given movable object is ignored by the collision test
void	kcd_act_grp (int grp_id)
	the group of links of the given robot is considered by the collision test
void	kcd_deact_grp (int grp_id)
	the group of links of the given robot is ignored by the collision test
void	kcd_act_obst (int ext_obj_id)
void	kcd_deact_obst (int ext_obj_id)
int	kcd_obst_is_act (int ext_obj_id)
void	kcd_act_mo_pair (kcd_col_handle *handlePt, int kcd_id1, int kcd_id2)
	Activate the test of collision and the distance computation between two movable objects.
void	kcd_deact_mo_pair (kcd_col_handle *handlePt, int kcd_id1, int kcd_id2)
	Deactivate the test of collision and the distance computation between two movable objects.
void	kcd_act_col_mo_pair (kcd_col_handle *handlePt, int kcd_id1, int kcd_id2)
	Activate the test of collision between two movable objects.
void	kcd_deact_col_mo_pair (kcd_col_handle *handlePt, int kcd_id1, int kcd_id2)
	Deactivate the test of collision between two movable objects.
void	kcd_act_dist_mo_pair (kcd_col_handle *handlePt, int kcd_id1, int kcd_id2)
	Activate the distance computation between two movable objects.
void	kcd_deact_dist_mo_pair (kcd_col_handle *handlePt, int kcd_id1, int kcd_id2)
	Deactivate the distance computation between two movable objects.
void	kcd_act_mo_env (kcd_col_handle *handlePt, int kcd_id)
	Activate the test of collision and the distance computation between a movable object and the environment..
void	kcd_deact_mo_env (kcd_col_handle *handlePt, int kcd_id)
	Deactivate the test of collision and the distance computation between a movable object and the environment..
void	kcd_act_col_mo_env (kcd_col_handle *handlePt, int kcd_id)
	Activate the test of collision between a movable object and the environment..
void	kcd_deact_col_mo_env (kcd_col_handle *handlePt, int kcd_id)
	Deactivate the test of collision between a movable object and the environment..
void	kcd_act_dist_mo_env (kcd_col_handle *handlePt, int kcd_id)
	Activate the distance computation between a movable object and the environment..
void	kcd_deact_dist_mo_env (kcd_col_handle *handlePt, int kcd_id)
	Deactivate the distance computation between a movable object and the environment..
void	kcd_act_grp_pair (kcd_col_handle *handlePt, int grp_id1, int grp_id2)
	Activate the test of collision between two groups of movable object.
void	kcd_deact_grp_pair (kcd_col_handle *handlePt, int grp_id1, int grp_id2)
	Deactivate the test of collision between two groups of movable object.
void	kcd_act_grp_env (kcd_col_handle *handlePt, int grp_id)
	Activate the test of collision between a groups of movable object and the environment.
void	kcd_deact_grp_env (kcd_col_handle *handlePt, int grp_id)
	Deactivate the test of collision between a group of movable object and the environment.
void	kcd_deactivate_all_mo (kcd_col_handle *handlePt)
	Deactivate all the test of collision.
int	kcd_mo_is_act (int mo_id)
	Returns if given movable object is activated.
int	kcd_grp_is_act (int grp_id)
	Returns if given group of movable object is activated.
int	kcd_mo_belongs_to_group (int mobj_id)
	see id a mo belongs to a group
int	kcd_mo_pair_is_act (kcd_col_handle *handlePt, int kcd_id1, int kcd_id2)
	Returns if there is a test of collision or a distance computation between two movable objects.
int	kcd_col_mo_pair_is_act (kcd_col_handle *handlePt, int kcd_id1, int kcd_id2)
	Returns if there is a test of collision between two movable objects.
int	kcd_dist_mo_pair_is_act (kcd_col_handle *handlePt, int kcd_id1, int kcd_id2)
	Returns if there is a distance computation between two movable objects.
int	kcd_mo_env_is_act (kcd_col_handle *handlePt, int kcd_id)
	Returns if there is a test of collision or a distance computation between a movable object and the environment..
int	kcd_col_mo_env_is_act (kcd_col_handle *handlePt, int kcd_id)
	Returns if there is a test of collision between a movable object and the environment..
int	kcd_dist_mo_env_is_act (kcd_col_handle *handlePt, int kcd_id)
	Returns if there is a distance computation between a movable object and the environment..
int	kcd_grp_pair_is_act (kcd_col_handle *handlePt, int grp_id1, int grp_id2)
	Returns if there is a test of collision between two groups of movable objects.
int	kcd_grp_env_is_act (kcd_col_handle *handlePt, int grp_id)
	Returns if there is a test of collision between a group of movable objects and the environment.
kcd_col_handle *	kcd_create_handle (void)
	Create and initialize a kcd collision handle.
kcd_col_handle *	kcd_copy_handle (kcd_col_handle *handlePt)
	Copy a kcd collision handle to a new structure.
void	kcd_copy_handle_into (kcd_col_handle *src_handlePt, kcd_col_handle *dest_handlePt)
	Copy a kcd collision handle into an other structure.
void	kcd_add_handle_into (kcd_col_handle *src_handlePt, kcd_col_handle *dest_handlePt)
	Merge two kcd collision handle (sum of collision tests)
void	kcd_sub_handle_into (kcd_col_handle *src_handlePt, kcd_col_handle *dest_handlePt)
	Merge two kcd collision handle (subtraction of collision tests)
void	kcd_deactivate_all_handle (kcd_col_handle *handlePt)
	Deactive all collision test between movable object and the environment.
void	kcd_destroy_handle (kcd_col_handle *handlePt)
	Release the memory of the kcd collisions handle.
kcd_col_handle *	kcd_get_cur_handle (void)
	Get the current collision handle.
void	kcd_set_cur_handle (kcd_col_handle *handlePt)
	Put a new collision handle as the current collision handle.
void	kcd_set_aabb_on_mo (int kcd_ext_o)
	user calls this function when he/she wants KCD to compute the AABB around (moved) movable object given by kcd_ext_o
int	kcd_robot_collides_itself (int robot_number, int with_report, double *min_dist, int *near_obs)
	Group of movable objects tests for autocollision.
int	kcd_robot_collides_robot (int robot_number1, int robot_number2, int with_report)
	returns TRUE if given groups of movable objects collide,
int	kcd_robot_vs_robot (int robot_number1, int robot_number2, int with_report, double *min_dist_estimate, int *nearest_obstacle)
int	kcd_robot_collides (int robot_id, int with_report, double *min_dist_estimate, int *nearest_obstacle)
	looks only for collision between given robot and static objects
int	kcd_collision_exists (int with_report, double *min_dist_estimate)
	looks for the existance of collision for any robot or movable object. This is a general function that tests all possible collisions.
int	kcd_mo_collides (int mobj_id, int with_report, double *min_dist_estimate, int *nearest_obstacle)
	looks only for collision between given mo and static objects
int	kcd_robot_collides_mo (int robot_id, int mo_id)
	returns TRUE if given robot collides with given movable object
int	kcd_robot_vs_mo (int robot_id, int mo_id, int with_report, double *min_dist_estimate, int *nearest_obstacle)
	tests a group of movable objects against a movable object
int	kcd_mo_collides_mo (int mo1, int mo2)
	tests two movable objects for collision (NO_REPORT), returns TRUE if two movable objects collide, FALSE otherwise
int	kcd_mo_vs_mo (int mo1, int mo2, int with_report, double *min_dist_estimate, int *nearest_obstacle)
	tests two movable objects for collision
void	kcd_set_tolerance (double epsilon)
	sets tolerance value to epsilon
void	kcd_ignore_tolerance ()
	resets tolerance value to zero (does the same as kcd_set_tolerance(0.0))
void	kcd_set_relative_error (double value)
	sets the value of kcd_epsilon in kcd, only usefull for exact distances
double	kcd_get_relative_error ()
	gets the value of kcd_epsilon in kcd
void	kcd_init_min_vol_of_obj_detail (double one_dim)
	sets smallest undividable volume for a bounding box before initialization of OBB(-tree)s and AABB hierarchy (to be called before definition of an environment)
void	kcd_set_min_vol_of_obj_detail (double one_dim)
	sets smallest undividable volume for a bounding box (must be larger than the initial value), stores original value used at initalization, uses the smallest undividable volume in collision test functions
void	kcd_ignore_min_vol_of_obj_detail ()
	resets smallest undividable volume for a bounding box to original value used at initialization by the user (or to 0.0 by default, when the user didn't specify at initialization)
int	kcd_report_get_cor_mo (int kcd_obj_id)
	get for a given kcd_obj_id the corresponding mo_id or so_id
int	kcd_robot_collides_something (int i, int with_report, double *min_dist_estimate)
int	kcd_robot_collides_something_except_specified_robot (int i, int deviceToIgnore, int with_report, double *min_dist_estimate)
int	kcd_nof_obst_to_add ()
void	kcd_addObst_beg_scene (int current_scene, int tot_nof_prims, int nof_st_obj)
void	kcd_addObst_end_scene ()
void	kcd_addObst_beg_obj ()
int	kcd_addObst_add_prim (void *primPt)
int	kcd_addObst_end_obj ()
int	kcd_get_nof_objects ()
Variables
kcd_scene_data_p	kcd_scene_data_arr = NULL

---

Detailed Description

This files contains API functions of KCD.

---

Function Documentation

void deconnect_kcd_data

(

)

Cleans up KCD and resets the data.

Note:

calls clean_kcd_col_data() and set_kcd_data_null()

void kcd_act_col_mo_env	(	kcd_col_handle *	handlePt,
		int	kcd_id
	)

Activate the test of collision between a movable object and the environment..

Parameters:

handlePt,:	The kcd collision handle.
kcd_id,:	The index of the movable object.

Note:

If the group of this movable object has no test with the environment, then it activate the collision between this group and the environment.

In other case it doesn't change the activation of groups.

void kcd_act_col_mo_pair	(	kcd_col_handle *	handlePt,
		int	kcd_id1,
		int	kcd_id2
	)

Activate the test of collision between two movable objects.

Parameters:

handlePt,:	The kcd collision handle.
kcd_id1,:	The index of the first movable object.
kcd_id2,:	The index of the second movable object.

Note:

If the groups of those two movable objects have no test between them, then it activate the collision between those two groups.

In other case it doesn't change the activation between groups.

void kcd_act_dist_mo_env	(	kcd_col_handle *	handlePt,
		int	kcd_id
	)

Activate the distance computation between a movable object and the environment..

Parameters:

handlePt,:	The kcd collision handle.
kcd_id,:	The index of the movable object.

Note:

If the group of this movable object has no test with the environment, then it activate the collision between this group and the environment.

In other case it doesn't change the activation of groups.

void kcd_act_dist_mo_pair	(	kcd_col_handle *	handlePt,
		int	kcd_id1,
		int	kcd_id2
	)

Activate the distance computation between two movable objects.

Parameters:

handlePt,:	The kcd collision handle.
kcd_id1,:	The index of the first movable object.
kcd_id2,:	The index of the second movable object.

Note:

If the groups of those two movable objects have no test between them, then it activate the collision between those two groups.

In other case it doesn't change the activation between groups.

void kcd_act_grp

(

int

grp_id

)

the group of links of the given robot is considered by the collision test

Warning:

grp_id < total number of groups

void kcd_act_grp_env	(	kcd_col_handle *	handlePt,
		int	grp_id
	)

Activate the test of collision between a groups of movable object and the environment.

Parameters:

handlePt,:	The kcd collision handle.
grp_id,:	The index of the movable objects group.

Note:

This function doesn't change the links between movable object. This links could be modified only by kcd_act_mo_env() or kcd_deact_mo_env().

grp_id == -1 activate the set of movable objects without group.

void kcd_act_grp_pair	(	kcd_col_handle *	handlePt,
		int	grp_id1,
		int	grp_id2
	)

Activate the test of collision between two groups of movable object.

Parameters:

handlePt,:	The kcd collision handle.
grp_id1,:	The index of the first movable objects group.
grp_id2,:	The index of the second movable objects group.

Note:

This function doesn't change the links between movable object. This links could be modified only by kcd_act_mo_pair() or kcd_deact_mo_pair().

If (grp_id1 == grp_id2) then this active the autocollision.

grp_id1 == -1 activate the set of movable objects without group.

void kcd_act_mo_env	(	kcd_col_handle *	handlePt,
		int	kcd_id
	)

Activate the test of collision and the distance computation between a movable object and the environment..

Parameters:

handlePt,:	The kcd collision handle.
kcd_id,:	The index of the movable object.

Note:

If the group of this movable object has no test with the environment, then it activate the collision between this group and the environment.

In other case it doesn't change the activation of groups.

void kcd_act_mo_pair	(	kcd_col_handle *	handlePt,
		int	kcd_id1,
		int	kcd_id2
	)

Activate the test of collision and the distance computation between two movable objects.

Parameters:

handlePt,:	The kcd collision handle.
kcd_id1,:	The index of the first movable object.
kcd_id2,:	The index of the second movable object.

Note:

If the groups of those two movable objects have no test between them, then it activate the collision between those two groups.

In other case it doesn't change the activation between groups.

void kcd_add_handle_into	(	kcd_col_handle *	src_handlePt,
		kcd_col_handle *	dest_handlePt
	)

Merge two kcd collision handle (sum of collision tests)

Note: It is an "or" opperation between all flags.

Warning:

The number of movable object must be the same in both handle.

Parameters:

src_handlePt,:	The source kcd collision handle.
dest_handlePt,:	The kcd collision handle that must store the sum.

int kcd_add_prim

(

void *

primPt

)

creates OBB's on the primitives

• creates OBB on sphere, cylinder, box, cube, cone, convex_facet, convex_polyhedron;
• creates OBB-tree on all OBBs of the convex facets defined in a polyhedron;
• places the OBB at pos0
• stores which solids and/or polyhedrons belong to currently defined object

Returns:

primitive_id

void kcd_beg_obj

(

int

can_move

)

adding an object

Parameters:

can_move

if can_move is FALSE, the object will be considered as a static obstacle.

Note:

will be followed by a number of calls to kcd_add_prim()

void kcd_beg_scene	(	int	tot_nof_prims,
		int	nof_st_obj,
		int	nof_mo_grps,
		int	nof_mov_obj
	)

Initializes some internal KCD data structures.

Parameters:

tot_nof_prims	the number of primitives in the scene (polyhedrons + Solids)
nof_st_obj	the number of static objects in data structure of the user
nof_mo_grps	the number of groups of movable objects the user will define
nof_mov_obj	the number of movable objects in data structure of the user

Note:

will be followed by a non-zero number of sequences kcd_beg_obj(), kcd_add_prim(), kcd_end_obj()

int kcd_col_mo_env_is_act	(	kcd_col_handle *	handlePt,
		int	kcd_id
	)

Returns if there is a test of collision between a movable object and the environment..

Parameters:

handlePt,:	The kcd collision handle.
kcd_id,:	The index of the movable object.

Returns:

TRUE if given pair of movable object and environment exists and is activated, FALSE otherwise

Remarks:

Returns TRUE even if the collision between its group and the environment is deactivate and so even if no collision test is done.

int kcd_col_mo_pair_is_act	(	kcd_col_handle *	handlePt,
		int	kcd_id1,
		int	kcd_id2
	)

Returns if there is a test of collision between two movable objects.

Parameters:

handlePt,:	The kcd collision handle.
kcd_id1,:	The index of the first movable object.
kcd_id2,:	The index of the second movable object.

Returns:

TRUE if given pair of movable objects exists and is activated, FALSE otherwise

Remarks:

Returns TRUE even if the collision between their groups are deactivate and so even if no collision test is done.

int kcd_collision_exists	(	int	with_report,
		double *	min_dist_estimate
	)

looks for the existance of collision for any robot or movable object. This is a general function that tests all possible collisions.

int kcd_collision_exists(int with_report, double *min_dist_estimate)

Parameters:

with_report

This parameter determines how the collision checker tests

Note:

for collision tests between movable objects (self-collision, collision between two groups or between a group and a mo or between two mo's) only those pairs of group elements are verified for which a collision pair was defined

Todo:

documentation of the with_report parameter

kcd_col_handle* kcd_copy_handle

(

kcd_col_handle *

handlePt

)

Copy a kcd collision handle to a new structure.

Parameters:

handlePt,:

The kcd collision handle that must be copied.

Returns:

The kcd collision handle. NULL if there isn't enough memory.

void kcd_copy_handle_into	(	kcd_col_handle *	src_handlePt,
		kcd_col_handle *	dest_handlePt
	)

Copy a kcd collision handle into an other structure.

Warning:

The number of movable object must be the same in both handle.

Parameters:

src_handlePt,:	The kcd collision handle that must be copied.
dest_handlePt,:	The kcd collision handle that must store the copy.

kcd_col_handle* kcd_create_handle

(

void

)

Create and initialize a kcd collision handle.

Note: this function deactivate all tesst of collisions.

Parameters:

nof_mos,:

The number of movable object.

Returns:

The kcd collision handle. NULL if there isn't enough memory.

void kcd_deact_col_mo_env	(	kcd_col_handle *	handlePt,
		int	kcd_id
	)

Deactivate the test of collision between a movable object and the environment..

Parameters:

handlePt,:	The kcd collision handle.
kcd_id,:	The index of the movable object.

Note:

If the group of this movable object has no test with the environment, then it deactivate the collision between this group and the environment.

In other case it doesn't change the activation of groups.

void kcd_deact_col_mo_pair	(	kcd_col_handle *	handlePt,
		int	kcd_id1,
		int	kcd_id2
	)

Deactivate the test of collision between two movable objects.

Parameters:

handlePt,:	The kcd collision handle.
kcd_id1,:	The index of the first movable object.
kcd_id2,:	The index of the second movable object.

Note:

If the groups of those two movable objects have no test between them, then it deactivate the collision between those two groups.

In other case it doesn't change the activation between groups.

void kcd_deact_dist_mo_env	(	kcd_col_handle *	handlePt,
		int	kcd_id
	)

Deactivate the distance computation between a movable object and the environment..

Parameters:

handlePt,:	The kcd collision handle.
kcd_id,:	The index of the movable object.

Note:

If the group of this movable object has no test with the environment, then it deactivate the collision between this group and the environment.

In other case it doesn't change the activation of groups.

void kcd_deact_dist_mo_pair	(	kcd_col_handle *	handlePt,
		int	kcd_id1,
		int	kcd_id2
	)

Deactivate the distance computation between two movable objects.

Parameters:

handlePt,:	The kcd collision handle.
kcd_id1,:	The index of the first movable object.
kcd_id2,:	The index of the second movable object.

Note:

If the groups of those two movable objects have no test between them, then it deactivate the collision between those two groups.

In other case it doesn't change the activation between groups.

void kcd_deact_grp

(

int

grp_id

)

the group of links of the given robot is ignored by the collision test

Warning:

grp_id < total number of groups

void kcd_deact_grp_env	(	kcd_col_handle *	handlePt,
		int	grp_id
	)

Deactivate the test of collision between a group of movable object and the environment.

Parameters:

handlePt,:	The kcd collision handle.
grp_id,:	The index of the movable objects group.

Note:

This function doesn't change the links between movable object. This links could be modified only by kcd_act_mo_env() or kcd_deact_mo_env(). Then a call to kcd_act_grp_env() restore all those links.

grp_id == -1 deactivate the set of movable objects without group.

void kcd_deact_grp_pair	(	kcd_col_handle *	handlePt,
		int	grp_id1,
		int	grp_id2
	)

Deactivate the test of collision between two groups of movable object.

Parameters:

handlePt,:	The kcd collision handle.
grp_id1,:	The index of the first movable objects group.
grp_id2,:	The index of the second movable objects group.

Note:

This function doesn't change the links between movable object. This links could be modified only by kcd_act_mo_pair() or kcd_deact_mo_pair(). Then a call to kcd_act_grp_pair() restore all those links.

if (grp_id1 == grp_id2) then this deactive the autocollision.

grp_id1 == -1 deactivate the set of movable objects without group.

void kcd_deact_mo_env	(	kcd_col_handle *	handlePt,
		int	kcd_id
	)

Deactivate the test of collision and the distance computation between a movable object and the environment..

Parameters:

handlePt,:	The kcd collision handle.
kcd_id,:	The index of the movable object.

Note:

If the group of this movable object has no test with the environment, then it deactivate the collision between this group and the environment.

In other case it doesn't change the activation of groups.

void kcd_deact_mo_pair	(	kcd_col_handle *	handlePt,
		int	kcd_id1,
		int	kcd_id2
	)

Deactivate the test of collision and the distance computation between two movable objects.

Parameters:

handlePt,:	The kcd collision handle.
kcd_id1,:	The index of the first movable object.
kcd_id2,:	The index of the second movable object.

Note:

If the groups of those two movable objects have no test between them, then it deactivate the collision between those two groups.

In other case it doesn't change the activation between groups.

void kcd_deactivate_all_handle

(

kcd_col_handle *

handlePt

)

Deactive all collision test between movable object and the environment.

Parameters:

handlePt,:

The kcd collision handle.

void kcd_deactivate_all_mo

(

kcd_col_handle *

handlePt

)

Deactivate all the test of collision.

Parameters:

handlePt,:

The kcd collision handle.

int kcd_def_mo_grp	(	int *	arr_kcd_ids,
		int	nof_mo_ids
	)

makes group of several given movable objects

Parameters:

arr_mo_ids	an array of kcd-ids of objects
nof_mo_ids	number of entries in array arr_mo_ids

Returns:

a group-id (e.g. can be seen as a robot-id)

Warning:

movable objects previously defined and not in other group

void kcd_destroy_handle

(

kcd_col_handle *

handlePt

)

Release the memory of the kcd collisions handle.

Parameters:

handlePt,:

The kcd collision handle.

Note:

This function cannot destroy the default collision handle.

int kcd_dist_mo_env_is_act	(	kcd_col_handle *	handlePt,
		int	kcd_id
	)

Returns if there is a distance computation between a movable object and the environment..

Parameters:

handlePt,:	The kcd collision handle.
kcd_id,:	The index of the movable object.

Returns:

TRUE if given pair of movable object and environment exists and is activated, FALSE otherwise

Remarks:

Returns TRUE even if the collision between its group and the environment is deactivate and so even if no collision test is done.

int kcd_dist_mo_pair_is_act	(	kcd_col_handle *	handlePt,
		int	kcd_id1,
		int	kcd_id2
	)

Returns if there is a distance computation between two movable objects.

Parameters:

handlePt,:	The kcd collision handle.
kcd_id1,:	The index of the first movable object.
kcd_id2,:	The index of the second movable object.

Returns:

TRUE if given pair of movable objects exists and is activated, FALSE otherwise

Remarks:

Returns TRUE even if the collision between their groups are deactivate and so even if no collision test is done.

int kcd_end_obj

(

)

creates OBB-tree on all single OBBs and on all roots of OBB-trees of the primitives and polyhedrons in the object

Returns:

returns object identifier: unique number for each object (static or movable)

int kcd_end_scene

(

)

builds remaining internal hierarchies necessary for KCD

modifies remaining internal hierarchies necessary for KCD

Note:

Builds AABB hierarchy, and constructs OBB-trees

Returns:

kcd_scene_id an identifier of the scene

Note:

Modifies AABB hierarchy, and connects OBB-trees to new AABBs

kcd_col_handle* kcd_get_cur_handle

(

void

)

Get the current collision handle.

Returns:

The current kcd collision handle.

int kcd_get_is_moved

(

int

mo_id

)

returns whether or not the movable object must be tested for collision again (whether or not it moved more recently than the latest collision test)

Parameters:

mo_id

mo_id-th movable (!) object

Returns:

TRUE if mo_id-th movable object moved recently, FALSE otherwise

int kcd_get_nof_mos

(

)

Get the number of movable objects known by KCD.

Note:

used to test all different movable objects for collision

int kcd_grp_env_is_act	(	kcd_col_handle *	handlePt,
		int	grp_id
	)

Returns if there is a test of collision between a group of movable objects and the environment.

Parameters:

handlePt,:	The kcd collision handle.
grp_id,:	The index of the movable objects group.

Returns:

TRUE if a group of movable objects is activated with the environment, FALSE otherwise

Note:

grp_id1 == -1 return the activation of the set of movable objects without group.

int kcd_grp_is_act

(

int

grp_id

)

Returns if given group of movable object is activated.

Returns:

Returns TRUE if given group is activated, FALSE otherwise

Note:

grp_id == -1 represents all the movable objects that are not in any group.

Warning:

grp_id < total number of groups

int kcd_grp_pair_is_act	(	kcd_col_handle *	handlePt,
		int	grp_id1,
		int	grp_id2
	)

Returns if there is a test of collision between two groups of movable objects.

Parameters:

handlePt,:	The kcd collision handle.
grp_id1,:	The index of the first movable objects group.
grp_id2,:	The index of the second movable objects group.

Returns:

TRUE if given pair of group of movable objects exists and is activated, FALSE otherwise

Note:

grp_id1 == -1 return the activation of the set of movable objects without group.

kcd_init_min_vol_of_obj_detail

(

double

one_dim

)

sets smallest undividable volume for a bounding box before initialization of OBB(-tree)s and AABB hierarchy (to be called before definition of an environment)

Parameters:

one_dim

the smalllest undividable volume is a cube or a square with sizes of length one_dim

int kcd_mo_belongs_to_group

(

int

mobj_id

)

see id a mo belongs to a group

Parameters:

mobj_id

id of the movable object

Returns:

TRUE if movable object belongs to a group FALSE otherwise

int kcd_mo_collides	(	int	mobj_id,
		int	with_report,
		double *	min_dist_estimate,
		int *	nearest_obstacle
	)

looks only for collision between given mo and static objects

Note:

with_report parameter determines the report

does not look for collision with other robots and mo-s

Todo:

verify utility of if(!(kcd_get_is_moved(kcd_ext_o)) )

int kcd_mo_collides_mo	(	int	mov_obj_id1,
		int	mov_obj_id2
	)

tests two movable objects for collision (NO_REPORT), returns TRUE if two movable objects collide, FALSE otherwise

Does not verify for definition of collision pair between given movable objects, it just calls kcd_mo_vs_mo with with_report set to NO_REPORT

Note:

WAS: int kcd_body_hits_body(int mo1, int mo2),

int kcd_mo_env_is_act	(	kcd_col_handle *	handlePt,
		int	kcd_id
	)

Returns if there is a test of collision or a distance computation between a movable object and the environment..

Parameters:

handlePt,:	The kcd collision handle.
kcd_id,:	The index of the movable object.

Returns:

TRUE if given pair of movable object and environment exists and is activated, FALSE otherwise

Remarks:

Returns TRUE even if the collision between its group and the environment is deactivate and so even if no collision test is done.

int kcd_mo_is_act

(

int

mo_id

)

Returns if given movable object is activated.

Returns:

Returns TRUE if given movable object is activated, FALSE otherwise

void kcd_mo_moved	(	int	kcd_obj_id,
		int	is_moved
	)

keeps track of status of a movable object since the latest call to KCD collision test

Parameters:

kcd_obj_id	kcd_obj_id-th object (static or movable) given by user in the current scene
is_moved	TRUE if object moved since last call to a collision test ( FALSE if not )

Note:

sets flag to is_moved allowing the collision test to avoid testing unmoved movable objects does nothing when kcd_obj_id-th object is a static one

int kcd_mo_pair_is_act	(	kcd_col_handle *	handlePt,
		int	kcd_id1,
		int	kcd_id2
	)

Returns if there is a test of collision or a distance computation between two movable objects.

Parameters:

handlePt,:	The kcd collision handle.
kcd_id1,:	The index of the first movable object.
kcd_id2,:	The index of the second movable object.

Returns:

TRUE if given pair of movable objects exists and is activated, FALSE otherwise

Remarks:

Returns TRUE even if the collision between their groups are deactivate and so even if no collision test is done.

int kcd_mo_vs_mo	(	int	mo1,
		int	mo2,
		int	with_report,
		double *	min_dist_estimate,
		int *	nearest_obstacle
	)

tests two movable objects for collision

This function has a different functionality depending on the with_report parameter (see also kcd_api.h)

Parameters:

mo1	id of the first movable object
mo1	id of the second movable object
with_report	will decide how the mo's are tested
*min_dist_estimate	depending on with_report this returns nothing, an exact or estimated distance
*nearest_obstacle

Note:

writtes the found result in the report

Bug:

nearest_obstacle contains bugs

void kcd_remember_scene

(

int

kcd_scene_id

)

Select a scene with the kcd_scene_id.

Parameters:

kcd_scene_id

when the user defined several scenes, this function selects the data created by KCD for the scene for which kcd_end_scene() has returned the kcd_env_id identifier

Note:

this function does not recompute the data structures but re-uses the earlier initialization

int kcd_report_get_cor_mo

(

int

kcd_obj_id

)

get for a given kcd_obj_id the corresponding mo_id or so_id

Parameters:

kcd_obj_id

is the id of the object in the list of all the KCD objects

Returns:

if it is a movable object a mo_id is return, this mo_id can be used to retrieve the information written in the reports of KCD

int kcd_robot_collides	(	int	robot_id,
		int	with_report,
		double *	min_dist_estimate,
		int *	nearest_obstacle
	)

looks only for collision between given robot and static objects

Parameters:

with_report

see documentation

Returns:

*min_dist_estimate shortest distance found

Note:

does not look for self-collision, for collision with other robots

int kcd_robot_collides_itself	(	int	robot_number,
		int	with_report,
		double *	min_dist,
		int *	near_obs
	)

Group of movable objects tests for autocollision.

• returns TRUE if given robot is self-colliding

• the with_report parameter determines the report made
• verifies only those pairs of group elements for which a collision pair was defined

int kcd_robot_collides_mo	(	int	robot_id,
		int	mo_id
	)

returns TRUE if given robot collides with given movable object

• does not verify for definition of collision pair between given movable object and an element of the given group.

• does not test self-collision of robot

int kcd_robot_collides_robot	(	int	robot_number1,
		int	robot_number2,
		int	with_report
	)

returns TRUE if given groups of movable objects collide,

Note:

does not test self-collision, verifies only those pairs of group elements for which a collision pair was defined

int kcd_robot_vs_mo	(	int	robot_id,
		int	mo_id,
		int	with_report,
		double *	min_dist_estimate,
		int *	nearest_obstacle
	)

tests a group of movable objects against a movable object

This function has a different functionality depending on the with_report parameter (see also kcd_api.h)

Parameters:

robot_id	the group_id of the movable objects
mo_id	id of the other movable object
with_report	will decide how the mo's are tested
*min_dist_estimate	depending on with_report this returns nothing, an exact or estimated distance
*nearest_obstacle

void kcd_set_cur_handle

(

kcd_col_handle *

handlePt

)

Put a new collision handle as the current collision handle.

Parameters:

handlePt,:

The kcd collision handle.

void kcd_set_min_vol_of_obj_detail

(

double

one_dim

)

sets smallest undividable volume for a bounding box (must be larger than the initial value), stores original value used at initalization, uses the smallest undividable volume in collision test functions

Parameters:

one_dim

the smalllest undividable volume is a cube or a square with sizes of length one_dim

void kcd_set_relative_error

(

double

value

)

sets the value of kcd_epsilon in kcd, only usefull for exact distances

kcd_set_relative_error(double epsilon)

Parameters:

epsilon

a value that has to be an percentage (0 <= epsilon < 100)

Note:

the given value will be divided by 100, kcd uses the parameter as a value between 0 and 1

works only with the DISTANCE EXACT option

void kcd_set_tolerance

(

double

epsilon

)

sets tolerance value to epsilon

Parameters:

epsilon

the size of the security distance

void kcd_sub_handle_into	(	kcd_col_handle *	src_handlePt,
		kcd_col_handle *	dest_handlePt
	)

Merge two kcd collision handle (subtraction of collision tests)

Note: It is an "dest and not src" opperation between all flags.

Warning:

The number of movable object must be the same in both handle.

Parameters:

src_handlePt,:	The source kcd collision handle.
dest_handlePt,:	The kcd collision handle that must store the sum.