Class: PhidgetsNative::Spatial

Inherits:
Device
  • Object
show all
Defined in:
ext/phidgets_native/spatial_ruby.c,
ext/phidgets_native/spatial_ruby.c

Overview

This class provides functionality specific to the “Spatial” device class. Primarily, this includes reporting of acceleration, compass, and orientation vectors.

Instance Method Summary collapse

Constructor Details

#new(serial_number) ⇒ Object

All phidget objects are created from the device serial number. Serial numbers are required to be Fixnums (aka “unsigned integers”).

Instance Method Details

#accelerometer ⇒ Array

This method returns an array of Float(s) which represent the accelerometer magnitude of each axis, in meters per second. These values are merely those which were most recently reported via the CPhidgetSpatial_set_OnSpatialData_Handler event handler.

Returns:

  • (Array)

#accelerometer_axes ⇒ Fixnum

This method returns the number of axis reported by the accelerometer. This number comes from the CPhidgetSpatial_getAccelerationAxisCount function.

Returns:

  • (Fixnum)

#accelerometer_max ⇒ Array

This method returns an array of Float(s) which represent the maximal value that an axis will report during a sample interval. These values come from the CPhidgetSpatial_getAccelerationMax function.

Returns:

  • (Array)

#accelerometer_min ⇒ Array

This method returns an array of Float(s) which represent the minimal value that an axis will report during a sample interval. These values come from the CPhidgetSpatial_getAccelerationMin function.

Returns:

  • (Array)

#accelerometer_to_dcm ⇒ Matrix

This method returns a 3x3 Matrix containing a direction cosine Matrix which represents the rotation of the current accelerometer value.

Returns:

  • (Matrix)

#accelerometer_to_euler ⇒ Array

This method returns a three element array of euler angles (yaw, roll, pitch) representing the vector of acceleration, as currently reflected by the spatial sensor.

Returns:

  • (Array)

#close ⇒ nil

This method will unregister the phidget event handlers, and free up all API resources associated with the phidget. This is an optional, but useful way to remove the object’s overhead before the GC kicks in and actually frees the resource.

Returns:

  • (nil)

#compass ⇒ Array

This method returns an array of Float(s) which represent the relative magnetic attraction of each axis. These values are merely those which were most recently reported via the CPhidgetSpatial_set_OnSpatialData_Handler event handler.

NOTE: Sometimes the phidget library won’t have values to report on this measurement due to “EPHIDGET_UNKNOWNVAL” errors. When we come up against this case, we return the last values that were reported successfully.

NOTE: You probably want this value in degrees. This is difficult, primarily due to the pre-requisite of knowing what the cross-product is of the ground plane (aka, the ground’s surface normal). I might add a ‘bad estimate’ of this vector in a future version of the library. E-mail the author if you need some sample code based on the accelerometer’s inverse vector.

Returns:

  • (Array)

#compass_axes ⇒ Fixnum

This method returns the number of axis reported by the compass. This number comes from the CPhidgetSpatial_getCompassAxisCount function.

Returns:

  • (Fixnum)

#compass_bearing ⇒ Float

This method returns a float representing the compass’ bearing, perpendicular to the ground plane, in radians. A radian of ‘pi’ is where the usb cable plugs in, and a radian of 0 is the opposite end (front) of the device. Note that this method returns the ‘magnetic’ North, and not ‘true’ North. Also note that accuracy is highly determined by the private method ‘gravity_to_roll_and_pitch’. Currently, gravity is merely assumed to be the output of the accelerometer_to_roll_and_pitch method. Feel free to extend the Spatial class and override the gravity_to_roll_and_pitch method, if you feel you have a better way to determine gravity. Your override’s return will be used automatically by this method, once defined.

Returns:

  • (Float)

#compass_bearing_to_dcm ⇒ Matrix

This method returns a 3x3 direction cosine Matrix which represents the rotation of the current compass_bearing vector in 3d space.

Returns:

  • (Matrix)

#compass_bearing_to_euler ⇒ Float

Probably this isn’t too useful, but it returns a three element array, of which the third element is the compass_bearing.

Returns:

  • (Float)

#compass_correction ⇒ Array

This method returns the current compass_correction parameters, which were previously supplied to the compass_correction= method. If no such corrections were supplied, the return is nil.

Returns:

  • (Array)

#compass_correction=(Arraycorrection_parameters) ⇒ Array

This method expects a thirteen digit array of Floats, which are passed to the CPhidgetSpatial_setCompassCorrectionParameters function. It returns the provided array.

Returns:

  • (Array)

#compass_max ⇒ Array

This method returns an array of Float(s) which represent the maximal value that an axis will report during a sample interval. These values come from the CPhidgetSpatial_getMagneticFieldMax function.

Returns:

  • (Array)

#compass_min ⇒ Array

This method returns an array of Float(s) which represent the minimal value that an axis will report during a sample interval. These values come from the CPhidgetSpatial_getMagneticFieldMin function.

Returns:

  • (Array)

#data_rate ⇒ FixNum

This method returns the current data_rate as was previously supplied to the data_rate= method. If no such rate was supplied, then this method returns the default rate, which is 16.

Returns:

  • (FixNum)

#data_rate=(FixNumrate_in_ms) ⇒ FixNum

This method expects a FixNum, which is passed to the CPhidgetSpatial_setDataRate function. This value is the number of milliseconds between device sampling reports, and it defaults to 16.

NOTE: For the case of 16, the data_rate as would be measured in Hz is 62.5: 1000/16 = 62.5 Hz

Returns:

  • (FixNum)

#data_rate_max ⇒ Fixnum

This method returns a Fixnum which represents the maximum supported data rate that is supported by the library. This value comes direct from the CPhidgetSpatial_getDataRateMax function.

NOTE: Keep in mind that the lower the value, the “higher” the rate.

Returns:

  • (Fixnum)

#data_rate_min ⇒ Fixnum

This method returns a Fixnum which represents the minimaly supported data rate that is supported by the library. This value comes direct from the CPhidgetSpatial_getDataRateMin function.

NOTE: Keep in mind that the higher the value, the “lower” the rate.

Returns:

  • (Fixnum)

#gyro ⇒ Array

This method returns an array of Float(s) which represent the normalized value of each axis on the gyro in degrees (0-359.9). These values are calculated by accumulating the delta measurements which are reported inside the CPhidgetSpatial_set_OnSpatialData_Handler event handler.

NOTE: There’s probably better algorithms to calculate this value than the one being used by this library. The algorithm used was merely the one found in the phidget-provided examples. Feel free to submit your algorithm for inclusion in this library if you know of a better way to do this.

Returns:

  • (Array)

#gyro_axes ⇒ Fixnum

This method returns the number of axis reported by the gyroscope. This number comes from the CPhidgetSpatial_getGyroAxisCount function.

Returns:

  • (Fixnum)

#gyro_max ⇒ Array

This method returns an array of Float(s) which represent the maximal value that an axis will report during a sample interval. These values come from the CPhidgetSpatial_getAngularRateMax function.

Returns:

  • (Array)

#gyro_min ⇒ Array

This method returns an array of Float(s) which represent the minimal value that an axis will report during a sample interval. These values come from the CPhidgetSpatial_getAngularRateMin function.

Returns:

  • (Array)

#gyro_to_dcm ⇒ Matrix

This method returns a 3x3 direction cosine Matrix which represents the rotation of the current gyroscope vector.

Returns:

  • (Matrix)

#orientation_to_dcm ⇒ Array

This method returns a 3x3 direction cosine Matrix, which represent the estimated AHRS orientation of the phidget in 3d space.

Returns:

  • (Array)

#orientation_to_euler ⇒ Array

This method returns a 3 element array, which represents the estimated AHRS orientation of the phidget in 3d space, in euler angles.

Returns:

  • (Array)

#orientation_to_quaternion ⇒ Array

This method returns a 4 element array consisting of floats, which represent the estimated AHRS orientation of the phidget.

Returns:

  • (Array)

#reset_compass_correction! ⇒ nil

Zero’s the compass correction parameters. This method calls the CPhidgetSpatial_resetCompassCorrectionParameters function.

Returns:

  • (nil)

#sample_rate ⇒ FixNum

For most Phidgets, an event handler processes the device state changes at some regular interval. For these devices, this method will return the rate of state changes measured in Hz.

Returns:

  • (FixNum)

#zero_gyro! ⇒ nil

Zero’s the gyro values, and reference point. Once this method is executed it takes approximately two seconds for the gyro to zero, and start returning its offsets. This method zero’s out the current gyro state vector and calls the CPhidgetSpatial_zeroGyro function.

Returns:

  • (nil)