Declare required stuffs to update mbs files from MbsData state and user wishes. More...

#include "mbs_data.h"

Classes
struct	UpdateInline
	Define modification to be done on a inline. More...

struct	UpdateShape
	Define modifications to be done on a basic shape. More...

struct	ExtForces_3D
	Define 3D field for showing an external force sensor. More...

struct	UpdateExtForces
	Define modifications to be done on external forces, or new to add. More...

struct	UpdateLinkForces
	Define modifications to be done on link force (1D), or new to add. More...

struct	UserUpdates

Enumerations
enum	{ SHAPE_NONE, SHAPE_BOX, SHAPE_CYLINDER, SHAPE_CONE, SHAPE_SPHERE }

Functions
int	mbs_update (MbsData mbs_data, UserUpdates user_update, const char filename_in, const char filename_out, int verbose)
	Open the specified MBS file, update it and save it on the specified name. More...

int	mbs_synchronize (MbsData mbs_data, MbsLoader mbs_loader)
	Synchronize the value of the loaded MBS with the data in the computed MBS. More...

int	mbs_update_user (UserUpdates user_update, MbsLoader mbs_loader)
	Synchronize the value of the loaded MBS with user specific modification. More...

int	mbs_save (const char filename, MbsLoader mbs_loader)
	Save the mbs_info to disk. More...

int	mbs_data_to_info (MbsData mbs_data, MbsLoader mbs_loader)
	Update the MbsInfos with the given MbsData. More...

UserUpdates *	mbs_update_new_user ()
	Allocate and initialize an user update structure. More...

void	mbs_update_free_user (UserUpdates *uu)
	Free the provided user update structure. More...

UpdateInline *	mbs_update_new_inline ()
	Initialize and allocate an inline shape modification structure. More...

void	mbs_update_free_inline (UpdateInline *ui)
	Free the provided inline shape modification structure. More...

int	mbs_update_insert_inline (UserUpdates user_update, int on_base, const char body_name, const char shape_name, const char shape_url, double position[3], double scale[3], double rotation[3], double transparency, int prj_relative_url, int visible)
	Insert instruction to update the content of a visualization inline shape. More...

UpdateShape *	mbs_update_new_shape ()
	Initialize and allocate an 3D shape modification structure. More...

void	mbs_update_free_shape (UpdateShape *ui)
	Free the provided 3D shape modification structure. More...

int	mbs_update_insert_shape (UserUpdates user_update, int on_base, const char body_name, const char shape_name, int shape_nature, double size[3], double radius, double *height, double position[3], double scale[3], double rotation[3], double transparency, int visible)
	Insert instruction to update the content of a visualization 3D shape. More...

ExtForces_3D *	mbs_update_new_extforce_3d (int show, int show_x, int show_y, int show_z, int show_resultant, int position_at_end, int color_x[3], int color_y[3], int color_z[3], int color_resultant[3], double diameter, double scale)
	Allocate and initialize a external force/torque visualization parameter. More...

void	mbs_update_free_link (UpdateLinkForces *link)
	Free the provided link forces modifications structure. More...

int	mbs_update_insert_link (UserUpdates user_update, const char name, const char first_body, const char first_point, const char second_body, const char second_point, int visible)
	Insert instruction to update the content of an link force. More...

ExtForces_3D *	mbs_update_dup_extforce_3d (ExtForces_3D *orig, int new_col_x[3], int new_col_y[3], int new_col_z[3], int new_col_res[3])
	Clone an existing 3D forces visualization and apply the colors change. More...

void	mbs_update_free_extforce_3d (ExtForces_3D *force_3d)
	Free the provided 3D force visualization structure. More...

UpdateExtForces *	mbs_update_new_extforce ()
	Initialize and allocate an external force modification structure. More...

void	mbs_update_free_extforce (UpdateExtForces *force)
	Free the provided external forces modifications structure. More...

int	mbs_update_insert_extforce (UserUpdates user_update, int on_base, const char body_name, const char point_name, char name, int comp_position, int comp_rotation, int comp_velocity, int comp_acceleration, int comp_jacobian, ExtForces_3D force_3d, ExtForces_3D torque_3d)
	Insert instruction to update the content of an external force. More...

Detailed Description

Declare required stuffs to update mbs files from MbsData state and user wishes.

Date: Aug. 2023

Author: Robotran Team

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
SHAPE_NONE
SHAPE_BOX
SHAPE_CYLINDER
SHAPE_CONE
SHAPE_SPHERE

Function Documentation

◆ mbs_data_to_info()

int mbs_data_to_info	(	MbsData *	mbs_data,
		MbsLoader *	mbs_loader
	)

Update the MbsInfos with the given MbsData.

Parameters

[out]	mbs_infos	The structure to be updated.
[in]	mbs_data	The structure containing the data.

Returns: MBS_INFO_SUCCESS or MBS_INFO_FAILURE

◆ mbs_save()

int mbs_save	(	const char *	filename,
		MbsLoader *	mbs_loader
	)

Save the mbs_info to disk.

Parameters

[in]	filename	Name of the file to be written.
[out]	mbs_infos	Pointer to the Mbs state.

Returns: MBS_INFO_SUCCESS or a specific MBSysC error code.

◆ mbs_synchronize()

int mbs_synchronize	(	MbsData *	mbs_data,
		MbsLoader *	mbs_loader
	)

Synchronize the value of the loaded MBS with the data in the computed MBS.

The user model are not updated!

Parameters

[in]	mbs_data	Pointer to the system state to be considered.
[out]	mbs_loader	Pointer to the Mbs loader with data to be updated.

Returns: MBS_INFO_SUCCESS or MBS_INFO_FAILURE

◆ mbs_update()

int mbs_update	(	MbsData *	mbs_data,
		UserUpdates *	user_update,
		const char *	filename_in,
		const char *	filename_out,
		int	verbose
	)

Open the specified MBS file, update it and save it on the specified name.

The user model are not updated!

If the input and output mbs_file matches, the file will be replaced inplace.

The extension of the files must matches.

Parameters

[in]	mbs_data	Pointer to the system state to be saved.
[in]	user_update	Pointer to the modification that are not related to the computation fields stored in MbsData. Can be NULL.
[in]	filename_in	Name of the mbs file to be loaded.
[in]	filename_out	Name of the mbs file to be written. If NULL is provided, `filename_in` is considered.
[in]	verbose	Verbosity level, from only errors (0) to full verbose (2).

Returns: MBS_INFO_SUCCESS or MBS_INFO_FAILURE

◆ mbs_update_dup_extforce_3d()

ExtForces_3D* mbs_update_dup_extforce_3d	(	ExtForces_3D *	orig,
		int	new_col_x[3],
		int	new_col_y[3],
		int	new_col_z[3],
		int	new_col_res[3]
	)

Clone an existing 3D forces visualization and apply the colors change.

Parameters

[in]	orig	The source structure to be cloned.
[in]	new_col_x	Optional, the new RGB colors (between 0-255) of the vector along x axis. Set NULL to avoid any modification from the source.
[in]	new_col_y	Optional, the new RGB colors (between 0-255) of the vector along y axis. Set NULL to avoid any modification from the source.
[in]	new_col_z	Optional, the new RGB colors (between 0-255) of the vector along z axis. Set NULL to avoid any modification from the source.
[in]	new_col_res	Optional, the new RGB colors (between 0-255) of the resultant vector. Set NULL to avoid any modification from the source.

Returns: The cloned and modified 3D forces visualization structure.

◆ mbs_update_free_extforce()

void mbs_update_free_extforce ( UpdateExtForces * force )

Free the provided external forces modifications structure.

Parameters

[in,out] force The memory to be freed.

◆ mbs_update_free_extforce_3d()

void mbs_update_free_extforce_3d ( ExtForces_3D * force_3d )

Free the provided 3D force visualization structure.

Should not be called by the user: the pointer is stored in the UserUpdates when provided to the function mbs_update_insert_extforce(). Then it is freed with the UserUpdates structure.

Parameters

[in,out] force_3d The memory to be freed.

◆ mbs_update_free_inline()

void mbs_update_free_inline ( UpdateInline * ui )

Free the provided inline shape modification structure.

Parameters

[in,out] ui The memory to be freed.

◆ mbs_update_free_link()

void mbs_update_free_link ( UpdateLinkForces * link )

Free the provided link forces modifications structure.

Parameters

[in,out] force The memory to be freed.

◆ mbs_update_free_shape()

void mbs_update_free_shape ( UpdateShape * ui )

Free the provided 3D shape modification structure.

Parameters

[in,out] ui The memory to be freed.

◆ mbs_update_free_user()

void mbs_update_free_user ( UserUpdates * uu )

Free the provided user update structure.

Parameters

[in,out] uu The memory to be freed.

◆ mbs_update_insert_extforce()

int mbs_update_insert_extforce	(	UserUpdates *	user_update,
		int	on_base,
		const char *	body_name,
		const char *	point_name,
		char *	name,
		int	comp_position,
		int	comp_rotation,
		int	comp_velocity,
		int	comp_acceleration,
		int	comp_jacobian,
		ExtForces_3D *	force_3d,
		ExtForces_3D *	torque_3d
	)

Insert instruction to update the content of an external force.

A new external force sensor can be created if the value of UserUpdates::allow_new is True.

WARNING: MEMORY POINTER FOR FORCE/TORQUE VISUALIZATION CANNOT BE PROVIDED TO MULTIPLE CALL OF THE FUNCTION. DOING SO WILL LEAD TO UNDEFINED BEHAVIOR. THE PROVIDED MEMORY WILL BE FREED ALONGSIDE WITH THE UserUpdates STRUCTURE. FREEING THEM OUTSIDE WILL LEAD TO UNDEFINED BEHAVIOR.

Parameters

[in,out]	user_update	Pointer to the structure collecting all modification to be done on the model.
[in]	on_base	If the shape is not on the base body set the flag to 0. Otherwise set to 1, and then the `body_name` is disregarded.
[in]	body_name	The name of the body on which the force sensor is placed. Can be NULL if the shape is on the base.
[in]	point_name	The name of the point, on the body, on which the sensor is located. If the sensor is at the origin of the body (not on a anchor point), set the name as "origin".
[in]	name	The name of the external force sensor. In case of adding new sensor(s), the name must be unique (not checked by the function). Specifying a sensor with an existing name will lead to undefined behavior at model loading and simulation execution.
[in]	comp_position	Optional, enable the symbolic generation of sensor position if greater than 0. Disable it if set to 0. Set it to a negative value to avoid any modification.
[in]	comp_rotation	Optional, enable the symbolic generation of sensor rotation if greater than 0. Disable it if set to 0. Set it to a negative value to avoid any modification.
[in]	comp_velocity	Optional, enable the symbolic generation of sensor velocity if greater than 0. Disable it if set to 0. Set it to a negative value to avoid any modification.
[in]	comp_acceleration	Optional, enable the symbolic generation of sensor acceleration if greater than 0. Disable it if set to 0. Set it to a negative value to avoid any modification.
[in]	comp_jacobian	Optional, enable the symbolic generation of sensor Jacobian matrix if greater than 0. Disable it if set to 0. Set it to a negative value to avoid any modification.
[in,out]	force_3d	Optional, structure specifying the visualization parameters of the forces vectors. The memory pointed is set in the UserUpdates structure and will be freed automatically. The same memory provided multiple time will lead to UNDEFINED behavior. Set to NULL to avoid modification.
[in,out]	torque_3d	Optional, structure specifying the visualization parameters of the forces vectors. The memory pointed is set in the UserUpdates structure and will be freed automatically. The same memory provided multiple time will lead to UNDEFINED behavior. Set to NULL to avoid modification.

Returns: MBS_INFO_FAILURE for error, MBS_INFO_SUCCESS for success.

◆ mbs_update_insert_inline()

int mbs_update_insert_inline	(	UserUpdates *	user_update,
		int	on_base,
		const char *	body_name,
		const char *	shape_name,
		const char *	shape_url,
		double	position[3],
		double	scale[3],
		double	rotation[3],
		double	transparency,
		int	prj_relative_url,
		int	visible
	)

Insert instruction to update the content of a visualization inline shape.

A new inline can be created if the value of UserUpdates::allow_new is True.

Parameters

[in,out]	user_update	Pointer to the structure collecting all modification to be done on the model.
[in]	on_base	If the shape is not on the base body set the flag to 0. Otherwise set to 1, and then the `body_name` is disregarded.
[in]	body_name	The name of the body on which the shape is placed. Can be NULL if the shape is on the base.
[in]	shape_name	The name of the shape.
[in]	shape_url	Optional, the filepath to the inline file. If the path is relative to the project path, set `prj_relative_url` and do not start the path with a path separator (ie: "/"). Set to NULL to keep existing file/url.
[in]	position	Optional, array of size 3 containing the new x, y, z position of the shape on the body. Provide NULL to avoid any modification.
[in]	scale	Optional, array of size 3 containing the new x, y, z scale of the shape on the body. Provide NULL to avoid any modification.
[in]	rotation	Optional, array of size 3 containing the new rotation around x, y, z axis of the shape on the body. The rotation are in radians. Provide NULL to avoid any modification.
[in]	transparency	Optional, the transparency value of the shape, 1 is fully transparent, 0 is fully visible. Set a negative value to avoid any modification.
[in]	prj_relative_url	Set to 1 if the provided `shape_url` is a relative path from the project path. Then "PRJPATH/" is append to the provided url. Set to 0 if no modification to the url is required.
[in]	visible	Optional, the visibility flag of the shape: 1 is visible while 0 is invisible. Set a negative value to avoid any modification.

Returns: MBS_INFO_FAILURE for error, MBS_INFO_SUCCESS for success.

◆ mbs_update_insert_link()

int mbs_update_insert_link	(	UserUpdates *	user_update,
		const char *	name,
		const char *	first_body,
		const char *	first_point,
		const char *	second_body,
		const char *	second_point,
		int	visible
	)

Insert instruction to update the content of an link force.

A new link force can be created if the value of UserUpdates::allow_new is True. Changing the ends of the link force also requires to set this flag.

Parameters

[in,out]	user_update	Pointer to the structure collecting all modification to be done on the model.
[in]	name	The name of the link force. In case of adding new link(s), the name must be unique (not checked by the function). Specifying a link with an existing name will lead to undefined behavior at model loading and simulation execution.
[in]	first_body	Name of the body located at the first extremity.
[in]	first_point	Name of the point located at the first extremity.
[in]	second_body	Name of the body located at the second extremity.
[in]	second_point	Name of the point located at the second extremity.
[in]	visible	Flag to set the visible property of the link in the 3D visualization.

Returns: MBS_INFO_FAILURE for error, MBS_INFO_SUCCESS for success.

◆ mbs_update_insert_shape()

int mbs_update_insert_shape	(	UserUpdates *	user_update,
		int	on_base,
		const char *	body_name,
		const char *	shape_name,
		int	shape_nature,
		double	size[3],
		double *	radius,
		double *	height,
		double	position[3],
		double	scale[3],
		double	rotation[3],
		double	transparency,
		int	visible
	)

Insert instruction to update the content of a visualization 3D shape.

The specified shape must already exists with the same shape (box, sphere...). If multiple shape with the same name and nature exist, only the first found is modified.

Parameters

[in,out]	user_update	Pointer to the structure collecting all modification to be done on the model.
[in]	on_base	If the shape is not on the base body set the flag to 0. Otherwhise set to 1, and then the `body_name` is disregarded.
[in]	body_name	The name of the body on which the shape is placed. Can be NULL if the shape is on the base.
[in]	shape_name	The name of the shape.
[in]	shape_nature	The nature of the shape among: SHAPE_BOX SHAPE_CYLINDER SHAPE_CONE SHAPE_SPHERE
[in]	size	Optional, set to NULL to avoid any modification. Disregarded for all shape except boxes. This is the size of the box along x, y and z axis
[in]	radius	Optional, set to NULL to avoid any modification. Disregarded for boxes. This is the size of the radius of the shape (sphere, cone base, cylinder).
[in]	height	Optional, set to NULL to avoid any modification. Disregarded for boxes and spheres. This is the length of the cylinder or the cone.
[in]	position	Optional, array of size 3 containing the new x, y, z position of the shape on the body. Provide NULL to avoid any modification.
[in]	scale	Optional, array of size 3 containing the new x, y, z scale of the shape on the body. Provide NULL to avoid any modification.
[in]	rotation	Optional, array of size 3 containing the new rotation around x, y, z axis of the shape on the body. The rotation are in radians. Provide NULL to avoid any modification.
[in]	transparency	Optional, the transparency value of the shape, 1 is fully transparent, 0 is fully visible. Set a negative value to avoid any modification.
[in]	visible	Optional, the visibility flag of the shape: 1 is visible while 0 is invisible. Set a negative value to avoid any modification.

Returns: MBS_INFO_FAILURE for error, MBS_INFO_SUCCESS for success.

◆ mbs_update_new_extforce()

UpdateExtForces* mbs_update_new_extforce ( )

Initialize and allocate an external force modification structure.

This function should not be called directly. The function mbs_update_insert_extforce() do the same but also check for mandatory fields.

Returns: An empty allocated structure for external forces modifications.

◆ mbs_update_new_extforce_3d()

ExtForces_3D* mbs_update_new_extforce_3d	(	int	show,
		int	show_x,
		int	show_y,
		int	show_z,
		int	show_resultant,
		int	position_at_end,
		int	color_x[3],
		int	color_y[3],
		int	color_z[3],
		int	color_resultant[3],
		double	diameter,
		double	scale
	)

Allocate and initialize a external force/torque visualization parameter.

An unique pointer/structure must be provided for each visualization of torque or force for each external force in the function mbs_update_insert_extforce(). Then the memory will be freed when freeing the UserUpdates structure.

Use mbs_update_dup_extforce_3d() to easily duplicate your force/torque visualization structure.

Parameters

[in]	show	Optional, flag to disable general vector visualization. Set a negative value to avoid any modification.
[in]	show_x	Optional, flag to disable visualization of vector along x axis. Set a negative value to avoid any modification.
[in]	show_y	Optional, flag to disable visualization of vector along y axis. Set a negative value to avoid any modification.
[in]	show_z	Optional, flag to disable visualization of vector along z axis. Set a negative value to avoid any modification.
[in]	show_resultant	Optional, flag to disable visualization of resultant vector. Set a negative value to avoid any modification.
[in]	position_at_end	Optional, if true the tip of the vectors are on the sensor, otherwise the tail are on the sensor. Set a negative value to avoid any modification.
[in]	color_x	Optional, the RGB colors (between 0-255) of the vector along x axis. Set NULL to avoid any modification.
[in]	color_y	Optional, the RGB colors (between 0-255) of the vector along y axis. Set NULL to avoid any modification.
[in]	color_z	Optional, the RGB colors (between 0-255) of the vector along z axis. Set NULL to avoid any modification.
[in]	color_resultant	Optional, the RGB colors (between 0-255) of the resultant vector. Set NULL to avoid any modification.
[in]	diameter	Optional, the diameter of the vector. Set zero to avoid any modification.
[in]	scale	Optional, the scale between the force/torque value and the length of the vector. Set zero to avoid any modification.

Returns: An initialized 3D forces visualization structure.

◆ mbs_update_new_inline()

UpdateInline* mbs_update_new_inline ( )

Initialize and allocate an inline shape modification structure.

This function should not be called directly. The function mbs_update_insert_inline() do the same but also check for mandatory fields.

Returns: An empty allocated structure for inline shape modifications.

◆ mbs_update_new_shape()

UpdateShape* mbs_update_new_shape ( )

Initialize and allocate an 3D shape modification structure.

This function should not be called directly. The function mbs_update_insert_shape() do the same but also check for mandatory fields.

Returns: An empty allocated structure for 3D shape modifications.

◆ mbs_update_new_user()

UserUpdates* mbs_update_new_user ( )

Allocate and initialize an user update structure.

Returns: Pointer to the initialized memory.

◆ mbs_update_user()

int mbs_update_user	(	UserUpdates *	user_update,
		MbsLoader *	mbs_loader
	)

Synchronize the value of the loaded MBS with user specific modification.

The updatable values are limited to the values that does not interfere with the body dynamics. Such values are not stored in the MbsData structure.

Parameters

[in]	user_update	Pointer to the user modifications be considered.
[out]	mbs_loader	Pointer to the Mbs loader with data to be updated.

Returns: MBS_INFO_SUCCESS or MBS_INFO_FAILURE

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ mbs_data_to_info()

◆ mbs_save()

◆ mbs_synchronize()

◆ mbs_update()

◆ mbs_update_dup_extforce_3d()

◆ mbs_update_free_extforce()

◆ mbs_update_free_extforce_3d()

◆ mbs_update_free_inline()

◆ mbs_update_free_link()

◆ mbs_update_free_shape()

◆ mbs_update_free_user()

◆ mbs_update_insert_extforce()

◆ mbs_update_insert_inline()

◆ mbs_update_insert_link()

◆ mbs_update_insert_shape()

◆ mbs_update_new_extforce()

◆ mbs_update_new_extforce_3d()

◆ mbs_update_new_inline()

◆ mbs_update_new_shape()

◆ mbs_update_new_user()

◆ mbs_update_user()