tsc_TsModes

The tsc_TsModes class is used to control, query and perform measurements on a Total Station. A tsc_TsModes object contains a setting for each mode that is settable on an instrument. To use the object, all modes that are needed on the instrument (such as Direct Reflex, Laser, etc) are first set to the required values, then an action method is called which will send all the modes to the instrument in the correct sequence.

The action methods always set all modes that have been specified, taking into account the current instrument state. If a mode is already set correctly on the instrument, then it is not sent again. This allows the programmer to set up the required modes and perform all total station operations without needing to query the current instrument state. If another application or task within survey core changes the instrument's state, it will be restored to the settings specified in the tsc_TsModes object before the action (eg: a measurement) is taken.

The modes in a tsc_TsModes object all start off as unspecified, which means any instrument operation that is initiated using the object will not alter that mode.

Class members

Enumerations

There are many enumerations for use with this class; they are listed at the bottom of this page.

Constructors

tsc_TsModes (class tsc_TsInstrument& instrument);
This constructs an empty modes object and binds it to the specified instrument.

General methods

int Identifier ();
Returns a unique identifer, allocated at construction, that identifies this tsc_TsModes instance. This can be used to tie an event back to the operation that caused it.

void PopulateFromInstrument();
Populate most of the tsc_TsModes settings from the currently connected instrument.

void PopulateOrientationFromInstrument();
Populate orientation information from the instrument. Sets Face, HA and VA.

void PopulateTargetFromNamedTarget(const tsc_String& target);
Populate the target settings (including Name) from the specified named target. See QueryTargetName below to obtain a valid target mane.

void PopulateTargetFromCurrentTarget();
Populate the target settings from the currently selected target (includes Name).

void PopulateTargetFromTarget(tsc_Target target);
Load target settings into the object from the tsc_Target.

tsc_XCodeList CurrentTargetHeightMeasurementMethods();
The available target height measurement methods based on the current system setting (not the modes object setting).

double CalculateTrueVerticalTargetHeight(const double& measuredHeight, x_Code measurementMethod);
Calculate the true height given the measured height and the method by which it was obtained.

double CalculateMeasuredTargetHeight(const double& trueVerticalHeight, x_Code measurementMethod);
Given a desired or known true vertical target height express that height in terms of a measurement given the measurement method.

tsc_TsEnvironment GetEnvironment () const;
Generate a tsc_TsEnvironment object from the modes instance. Note that the enivronment will based upon the current job environment but overridden by any specified modes settings.

void Reset();
Resets all modes within the object to unspecified.

void Abort();
Abort any currently running operation. Note that OnFailed may be called and any pending instrument requests may still occur.

bool InProgress () const;
Returns true if some action method is in progress or the class is waiting for a synchronous operation to complete (which could be caught in the stack frame).

bool Failed () const;
Returns true if the last or current operation failed (which includes time outs).

bool TimedOut () const;
Returns true if the last or current operation has timed out.

Action methods

The action methods come in two variants; synchronous and asynchronous. Synchronous method block execution until completion, whereas asynchronous methods return immediately and continue operating in the background. The default timeout is 30.0 seconds. Take great care using the synchronous methods, particularly in a tsc_Form class. See the page Pitfalls using Synchronous methods for an in-depth explanation of the problems.

Capability
bool SupportsChangeFace ();
Determine if the ChangeFace command is supported by the instrument.

bool SupportsTurnTo ();
Determine if the TurnTo command is supported by the instrument.

bool SupportsSetHorizontalCircle ();
Determine if the SetHorizontalCircle command is supported by the instrument.

bool SupportsResetHorizontalCircle ();
Determine if the horizontal circle of the instrument can be reset to the native sensor values. This is useful for removing an unknown offset when sharing a trusted physical station setup between applications.

bool SupportsSearch ();
Determine if the Search command is supported by the instrument.

bool SearchAvailable ();
Determine if the Search command is acheivable with the current tsc_TsModes settings.

Synchronous

These action methods do not return until the operation succeeds, fails, or times out. While the operation is in progress, Survey Core will continue to process messages for the calling thread which means that (for instance) a form that calls one of these methods will continue to redraw normally.

Important: Because form events continue to be processed while waiting, it may be necessary to prevent re-entry of the event handler while the instrument operation is in progress. Please see the sample code near the bottom of this page about how to avoid this problem.

Take care using the synchronous methods, particularly in a tsc_Form class. See the page Pitfalls using Synchronous methods for an in-depth explanation of the problems.

The monitor parameter specifies a class that implements the tsc_ITsModesMonitor interface for handling events resulting from the operation. It may be specified as NULL (or omitted), which avoids the use of event handlers, and the return code must be tested to determine if the operation succeeded. Any kind of failure or timeout returns false.

bool ApplyModes (class tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);
Sends all specified modes to the instrument and returns true if the operation succeeds. Unspecified modes, and modes that are already correctly set in the instrument are not sent.

bool ChangeFace (class tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);
Changes the instrument face with a 180° HA and VA turn. Any specified modes that are not correctly set on the instrument are sent before the change of face.

bool TurnTo (const tsc_RawCircle& location, tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);
Turns to the location specified by the supplied coordinate. The slope distance may be used to set the instrument focus where this is supported. Any specified modes that are not correctly set on the instrument are sent before the instrument is turned.

bool SetHorizontalCircle (const double& newSetting, tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);
Sets the instrument horizontal circle to the supplied value (radians) and waits until complete.

bool ResetHorizontalCircle (tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);
Resets the instrument horizontal circle to the native sensor (0.0 offset) and waits until complete.

bool Search (tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);
Sends the current mode changes (if any) to the instrument, searches for a target and waits until complete. If the modes object and or current instrument settings are not suitable for a search then the search will not occur and the settings will not be applied.

tsc_RawCircle Measure (tsc_TsMeasurementType type, tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);
Takes an EDM measurement. Any specified modes that are not correctly set on the instrument are sent before the measurement is taken. If the measurement in unsuccessful or aborted then a tsc_RawCircle containing all double_Null values is returned.

In all cases a return value of true means that the operation completed successfully. A value of false indicates that the tsc_TsModes object is busy or stuck in a wait, no total station is connected or the operation either timed out or failed.

Asynchronous

These methods are called in pairs; first a Start method, then a Wait method. If the tsc_TsModes object is destroyed before the operation is complete, it will be aborted.

Asynchronous methods are generally safer to use than their synchronous cousins. Synchronous methods block the stack and may cause serious problems if used incorrectly.

bool StartApplyModes (tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);

bool StartChangeFace (tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);

bool StartTurnTo (const tsc_RawCircle& location, tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);

bool StartSetHorizontalCircle (const double& newSetting, tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);

bool StartResetHorizontalCircle (tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);

bool StartSearch (tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);

bool StartMeasure (tsc_TsMeasurementType type, tsc_ITsModesMonitor* monitor = NULL, double timeout = DefaultTimeout);

These four methods are identical to their synchronous equivalents, except that they return immediately after the operations have been started on the instrument. This may take a little time, but significantly less than the entire time the operation will take. A return value of false indicates that the tsc_TsModes object is busy, no total station is connected or the operation immediately failed.

bool WaitForCompletion();
This method will wait until the preceding operation has completed. If the operation has already finished, it will not wait at all, and if no operation has ever been started on the tsc_TsModes instance it will wait forever.

tsc_RawCircle WaitForMeasure();
Waits for a measure operation to complete, and returns the results. If the previous operation was not a Measure, or the results have already been obtained, the returned object will contain double_Null values in its members.

tsc_RawCircle GetMeasureResult();
Similar to WaitForMeasure but does not wait. If a measurement is not started or is not complete then a double_Null tsc_RawCircle will be returned. Use this function inside the tsc_ITsModesMonitor::OnTsModesMeasurementComplete event handler to retrieve the result.

Mode setting and querying methods

Each mode type (Laser pointer, Direct reflex, tracklight, etc) has three methods; a Set method, a Clear method, and a Query method. All these methods return the same type - a tsc_ModesResult enumeration which describes the current mode as one of:

- tsmr_Unspecified - The mode has not been specified in this instance.
- tsmr_Specified - The mode has been specified, it is supported, and is read and/or write.
- tsmr_Supported - The mode is supported - does not imply the specified status.
- tsmr_Unsupported - The mode is unsupported - does not imply the specified status.

The query methods have two options specified by the tsc_QueryMode argument:

tsqm_QueryThis - Queries the tsc_TsModes instance.
tsqm_QueryInstrument - Queries the instrument.
tsqm_QuerySupported -
Queries the current connection and configuration to determine if the feature is currently supported. This type of query will use the result parameter to determine if a particular option is being tested (e.g.: finelock) making it an in/out parameter. Use Unknown or Unspecified values as input when referring to the overall setting.

Setting conflicts and resolution

Several of the 'active' settings are co-dependant and it is fairly easy to set conflicting values. tsc_TsModes will resolve most conflicts automatically when applied (without changing your state). Here is a short summary of common conflicts:

- Active working modes and Direct Reflex
- All laser pointers require Direct Reflex
- TargetName can specify Target DR status, as does the stand-alone DR setting
- Some prism types require a particular prism constant
- Most target settings cannot be applied to the DR Target.
- Remote target ID requires an active working mode.

DR/Working Mode/Laser Precedence (high to low)

- TargetName
- A DR target name forces DR on, working mode to Passive and Remote IDs off; a non DR target forces DR off and forces all Laser pointers off
- Working Mode
- An active working mode will force DR off and also forces all Laser pointers off; an inactive one will disable Remote IDs.
- DR
- If DR is off then all Laser pointers will be forced off; if DR is on then Remote IDs are disabled.
- Laser Pointers
- If Dr has not been specified so far then a laser pointer set on will turn on DR.
- Remote IDs
- If the DR has not been specified so far then these settings will disable DR and enable an active working mode.
- Target settings
- In the absence of any other controlling interests, if the target properties are incompatible with a DR target then a non-DR target is selected.

Prism Constant Precedence (high to low)

- TargetPrismType
- Some target types specify known prism constants.
- TargetPrism Constant

So you could see for example that it is possible to specify Working Mode: Autolock, Prism Constant:16mm and TargetName:Target DR. Which wins?

TargetName trumps autolock but the prism constant (which is unusual for a DR target) is retained.

TargetName:Target 1, Working Mode:Autolock, TargetPrismConstant:12mm and LaserPointer:On?

Target1 is set which is a non-DR target so the Working Mode can be Autolock, the prism constant to 12mm is compatible; the Laser pointer requires DR to work but is of low precedence and is ignored.

Also a Face setting will override a HA, VA setting pair. That is, given a choice, tsc_TsModes will change to the correct face in preference to turning to your specified angles (when the resulting faces would be different).

Note that we do not check target settings strongly. For example setting prism constant:16mm on a DR target will succeed though this setting is typically (but not always) invalid. We will not check beyond the DR mode to see if an appropriate prism type (which was unspecified) was currently selected.

On the other hand several of the modes have no conflicts and just act as refinements of other modes when they are active e.g. DRWeakSignal is only effective when DR is on - though the setting is set, SurveyCore will only use it when appropriate and tsc_TsModes will not activate DR on its behalf.

General Settings

These are active settings that, if set, will be applied directly and invoke dependencies (e.g. LaserPointer on will ensure DR will be on).

tsc_ModesResult SetLaserPointer (bool newSetting);

tsc_ModesResult ClearLaserPointer ();

tsc_ModesResult QueryLaserPointer (tsc_QueryMode mode, bool& result);

tsc_ModesResult SetHighPowerLaser (bool newSetting);

tsc_ModesResult ClearHighPowerLaser ();

tsc_ModesResult QueryHighPowerLaser (tsc_QueryMode mode, bool& result);

tsc_ModesResult SetTracklight (tsc_TsTracklightState newSetting);

tsc_ModesResult ClearTracklight ();

tsc_ModesResult QueryTracklight (tsc_QueryMode mode, tsc_TsTracklightState& result);

tsc_ModesResult SetDirectReflex (bool newSetting);

tsc_ModesResult ClearDirectReflex ();

tsc_ModesResult QueryDirectReflex (tsc_QueryMode mode, bool& result);

tsc_ModesResult SetMeasureMode (tsc_TsMeasureMode newSetting);

tsc_ModesResult ClearMeasureMode ();

tsc_ModesResult QueryMeasureMode (tsc_QueryMode mode, tsc_TsMeasureMode& result);

tsc_ModesResult SetWorkingMode (tsc_TsWorkingMode newSetting);

tsc_ModesResult ClearWorkingMode ();

tsc_ModesResult QueryWorkingMode (tsc_QueryMode mode, tsc_TsWorkingMode& result);

These are passive settings that, if set, will be applied but not invoke dependencies (e.g. PrismLongRange by itself will not disable DR).

tsc_ModesResult SetPrismLongRange (bool newSetting);

tsc_ModesResult ClearPrismLongRange ();

tsc_ModesResult QueryPrismLongRange (tsc_QueryMode mode, bool& result);

The distance must be with the Absolute<Min/Max>DrDistanceSetting values and smaller than the current or specified Maximum setting.

tsc_ModesResult SetMinimumDrDistance (double newSetting);

tsc_ModesResult ClearMinimumDrDistance ();

tsc_ModesResult QueryMinimumDrDistance (tsc_QueryMode mode, double& result);

The distance must be with the Absolute<Min/Max>DrDistanceSetting values and greater than the current or specified Minimum setting.

tsc_ModesResult SetMaximumDrDistance (double newSetting);

tsc_ModesResult ClearMaximumDrDistance ();

tsc_ModesResult QueryMaximumDrDistance (tsc_QueryMode mode, double& result);

tsc_ModesResult SetDrWeakSignal (bool newSetting);

tsc_ModesResult ClearDrWeakSignal ();

tsc_ModesResult QueryDrWeakSignal (tsc_QueryMode mode, bool& result);

tsc_ModesResult SetUserStandardDeviation (double newSetting);

tsc_ModesResult ClearUserStandardDeviation ();

tsc_ModesResult QueryUserStandardDeviation (double& result);

tsc_ModesResult SetUserDRStandardDeviation (double newSetting); // Will NOT force DR Mode on.

tsc_ModesResult ClearUserDRStandardDeviation ();

tsc_ModesResult QueryUserDRStandardDeviation (double& result);

tsc_ModesResult SetSearchWindowVA (double newSetting); // Radians. Controls window size, not location.

tsc_ModesResult ClearSearchWindowVA ();

tsc_ModesResult QuerySearchWindowVA (tsc_QueryMode mode, double& result);

tsc_ModesResult SetSearchWindowHA (double newSetting); // Radians. Controls window size, not location.

tsc_ModesResult ClearSearchWindowHA ();

tsc_ModesResult QuerySearchWindowHA (tsc_QueryMode mode, double& result);

tsc_ModesResult SetCompensator (bool newSetting); // Enable or disable the elevel compensator.

tsc_ModesResult ClearCompensator ();

tsc_ModesResult QueryCompensator (tsc_QueryMode mode, bool& result);

Orientation Settings

These are active settings.

tsc_ModesResult SetTurnToVertical (double newSetting);

tsc_ModesResult ClearTurnToVertical ();

tsc_ModesResult QueryTurnToVertical (tsc_QueryMode mode, double& result);

tsc_ModesResult SetTurnToHoriz (double newSetting);

tsc_ModesResult ClearTurnToHoriz ();

tsc_ModesResult QueryTurnToHoriz (tsc_QueryMode mode, double& result);

tsc_ModesResult SetFace (tsc_StationFace newSetting);

tsc_ModesResult ClearFace ();

tsc_ModesResult QueryFace (tsc_StationFace& result);

Target Settings

Target settings are active settings.

The target settings are dominated by the TargetName. If the TargetName is set then that target will be switched to, and any other target settings will be applied to the newly selected target. If the name is left unspecified then it is assumed that the target settings refer to the current target.

DR targets cannot accept most settings, for example they always have a target height of 0.0m; if the TargetName specifies a DR target then the other target settings will be ignored. If the TargetName is unspecified but the current target is a DR target then a non-DR target will be switched to (most recently used) to allow the other target settings to be applied.

Valid target names are retrievable by querying the current TargetName by using: QueryTargetName, or PopulateTargetFromCurrentTarget.

The target height measurement mode is a display mode that will affect the system target display, it will be ignored if an inappropriate x_Code is supplied and does not affect the (always true vertical) TargetHeight mode.

tsc_ModesResult SetTargetName (const tsc_String& newSetting);

tsc_ModesResult ClearTargetName ();

tsc_ModesResult QueryTargetName (tsc_QueryMode mode, tsc_String& result);

tsc_ModesResult SetTargetId (int newSetting);

tsc_ModesResult ClearTargetId ();

tsc_ModesResult QueryTargetId (tsc_QueryMode mode, int& result);

tsc_ModesResult SetTargetPrismType (tsc_TsTargetPrismType newSetting);

tsc_ModesResult ClearTargetPrismType ();

tsc_ModesResult QueryTargetPrismType (tsc_QueryMode mode, tsc_TsTargetPrismType& result);

tsc_ModesResult SetTargetIdCheckMode (tsc_TargetIdCheckMode newSetting);

tsc_ModesResult ClearTargetIdCheckMode ();

tsc_ModesResult QueryTargetIdCheckMode (tsc_QueryMode mode, tsc_TargetIdCheckMode& result);

tsc_ModesResult SetTargetHeight (double newSetting);

tsc_ModesResult ClearTargetHeight ();

tsc_ModesResult QueryTargetHeight (tsc_QueryMode mode, double& result);

enum tsc_TsWorkingMode

{

tswm_Unspecify = -1,

tswm_Manual, ///< Instrument doesn't lock on to targets

tswm_Autolock, ///< Instrument locks on to any valid target if it finds one.

tswm_Searchlock, ///< Same as autolock, but instrument will only lock on to targets when it searches.

tswm_Finelock, ///< Finelock, only Trimble S8/S9

tswm_LongRangeFinelock ///< Finelock long range, only Trimble S8/S9

};

tsc_TsMeasurementType

enum tsc_TsMeasurementType

{

tsmt_AnglesAndDistance = 0, ///< Angles and distance

tsmt_AnglesOnly ///< Angles only

};

Sample code

Synchronous operation, querying and setting modes

void ToggleLaserPointer(tsc_Instrument& instr)

{

static bool inProgress = false;

if (inProgress) return;

inProgress = true; // Prevent re-entry.

if (!instr.IsTs())

{

tsc_MessageBox::Show(X_Error, X_SSeriesInstrNotConnected);

return;

}

tsc_TsInstrument ts = _instr.AsTs();

tsmodes = tsc_TsModes(ts);

tsmodes.PopulateFromInstrument(); // Obtain the instrument's current state.

bool laserCurrentlyOn = false;

tsc_ModesResult result = tsmodes.QueryLaserPointer(tsqm_QueryInstrument, laserCurrentlyOn);

if (result == tsmr_Unsupported)

{

tsc_MessageBox::Show(X_Error, X_LaserPointer); // No laser capability.

return;

}

result = tsmodes.SetLaserPointer(!laserCurrentlyOn);

tsmodes.ApplyModes (); // Toggle laser setting and wait until completed.

// Now the laser is on

inProgress = false; // Allow re-entry.

}

Synchronous operation, measure a point

tsc_RawCircle Measure (tsc_TsInstrument& instr)

{

tsc_TsModes modes (instr);

modes.SetTargetName ("Target2");

modes.SetLaserPointer(false);

modes.SetDirectReflex(false);

modes.SetHighPowerLaser(false);

modes.SetTracklight(tstl_Off);

modes.SetTargetIdCheckMode(tstc_Passive);

modes.SetWorkingMode(tswm_Autolock);

modes.SetMeasureMode(tsmm_Fine);

tsc_SurveyCore::StatusMessage(X_Measuring, 3);

tsc_RawCircle circle = modes.Measure (tsmt_AnglesAndDistance);

return circle;

}