MirageComm Class Reference

Handles communication with Mirage to place and control an object in the environment. More...

#include <MirageComm.h>

Detailed Description

Handles communication with Mirage to place and control an object in the environment.

The MirageComm constructor will open a connection to Mirage (if not already open). Then call setName() to register a name for your object. Finally, assign a KinematicJoint via setKinematics() to provide information to configure and display your object.

You can reuse the MirageComm instance for multiple objects in Mirage, simply call setName() to change the name of the object being controlled. Alternatively, you can use multiple MirageComms with a single shared network connection. Each MirageComm tracks the name of the object is controlling and sends this state in each update to Mirage.

Parameters assigned by MirageComm are buffered until MirageComm hits its destructor, setName(), or flush() is called.

Objects are kept in the Mirage simulation until all network connections associated with that object are closed. However, if setPersist(true) is called, the object will be kept active even if all associated network connections are closed.

  #include "local/DeviceDrivers/MirageComm.h"
  #include "Wireless/netstream.h"
  ionetstream net;
  MirageComm mirage(net); // without arguments, makes connection to "localhost"
  mirage.setName("target");
  mirage.setPersist(true); // so we can close net without removing object
  KinematicJoint * k = new KinematicJoint; // this will hold object description
  k->model="Sphere";
  k->material="Pink";
  k->modelScale=plist::Point(15,15,15);
  mirage.setKinematics(k); // mirage will delete k after the flush
  mirage.setPosition(500,0,0); // place object at (500,0,0) mm
  // mirage destructor will automatically flush assigned attributes
  //   at end of scope, or you can call mirage.flush()

When you want to close the connection (e.g. remove the object "target" from previous example) just close the ionetstream connection. If you want to be "nice" about this, let MirageComm do it:

  ionetstream net; // or continue 'net' scope from above to avoid connection overhead
  MirageComm mirage(net);
  mirage.setName("target");
  mirage.setPersist(false); // disable persistance, object will be removed when 'net' is closed
  mirage.close(); // sends XML closing tags to make Mirage's parser feel warm and fuzzy

Note that if you can match the network connection scope to the desired lifetime of the object in Mirage (e.g. make 'net' a class member of your object's controller), then you don't need to call setPersist(), and can simply rely on objects being "garbage collected" when you eventually close the connection.

Definition at line 55 of file MirageComm.h.

List of all members.

Public Member Functions
	MirageComm (ionetstream &io, const std::string &host="localhost", unsigned short port=19785)
	Constructor, if io is not already connected, it will reconnect to host and port.
	~MirageComm ()
	destructor
bool	connect (const std::string &host, unsigned short port=19785)
	opens connection to Mirage
void	close ()
	Closes connection to Mirage.
MirageComm &	setName (const std::string &n)
	Indicates which object is being controlled.
MirageComm &	setPersist (bool persist)
	If passed 'true', this will prevent the current object from being removed when the connection is closed.
MirageComm &	setKinematics (KinematicJoint *kj)
	Assigns kinematic information to define the display and movement of the object, will delete kj after flush!
template<class T >
MirageComm &	setKinematicProperty (const std::string &paramName, const T &val)
	Assigns a value to a specific field of the root kinematic object.
MirageComm &	setPosition (float x, float y, float z)
	Controls position of the object.
MirageComm &	setPosition (const fmat::Column< 3 > &x)
	Controls position of the object.
MirageComm &	setPosition (const fmat::SubVector< 3 > &x)
	Controls position of the object.
MirageComm &	setPosition (const fmat::SubVector< 3, const fmat::fmatReal > &x)
	Controls position of the object.
MirageComm &	setPosition (const plist::Point &x)
	Controls position of the object.
MirageComm &	setOrientation (const fmat::Quaternion &q)
	Controls orientation of the object.
bool	flush ()
	Will cause previous 'set' calls to be transmitted to Mirage.
	operator bool () const
	returns true if the communication socket is still good
Protected Attributes
ionetstream &	comm
	connection to Mirage
plist::Primitive< std::string >	name
	name ("ID") of the current object in Mirage
plist::Dictionary	msg
	buffers settings to Mirage until flush();

Constructor & Destructor Documentation

MirageComm	(	ionetstream &	io,
		const std::string &	host = `"localhost"`,
		unsigned short	port = `19785`
	)

Constructor, if io is not already connected, it will reconnect to host and port.

If the connection fails, no status is returned, check io.is_open() or the MirageComm bool cast

Definition at line 59 of file MirageComm.h.

~MirageComm ( )

destructor

Definition at line 65 of file MirageComm.h.

Member Function Documentation

void close ( )

Closes connection to Mirage.

Any objects which have not had setPersist(true) and have not been "touched" by other connections will be removed from the environment.

Definition at line 79 of file MirageComm.h.

bool connect	(	const std::string &	host,
		unsigned short	port = `19785`
	)

opens connection to Mirage

Definition at line 68 of file MirageComm.h.

Referenced by MirageComm().

bool flush ( )

Will cause previous 'set' calls to be transmitted to Mirage.

Definition at line 174 of file MirageComm.h.

Referenced by close(), setName(), and ~MirageComm().

operator bool ( ) const

returns true if the communication socket is still good

Definition at line 185 of file MirageComm.h.

MirageComm& setKinematicProperty	(	const std::string &	paramName,
		const T &	val
	)

Assigns a value to a specific field of the root kinematic object.

Many times no joints are in use, and you only want to modify a subset of fields, without respecifying the kinematic description—this will let you do it.

Definition at line 116 of file MirageComm.h.

MirageComm& setKinematics ( KinematicJoint * kj )

Assigns kinematic information to define the display and movement of the object, will delete kj after flush!

This will delete kj after the next flush, so pass the result of kj->clone() if you don't want to lose your instance

Definition at line 106 of file MirageComm.h.

MirageComm& setName ( const std::string & n )

Indicates which object is being controlled.

If an object with this name already exists, subsequent 'set' calls will control that object. If no such object exists, a new one will be created. This implies a flush if any parameters have been set under the old name.

If no name has been set yet, inherit parameters (i.e. doesn't flush parameters without a name)

Definition at line 91 of file MirageComm.h.

MirageComm& setOrientation ( const fmat::Quaternion & q )

Controls orientation of the object.

Definition at line 166 of file MirageComm.h.

MirageComm& setPersist ( bool persist )

If passed 'true', this will prevent the current object from being removed when the connection is closed.

Definition at line 99 of file MirageComm.h.

MirageComm& setPosition ( const plist::Point & x )