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:

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

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:

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

Prism Constant Precedence (high to low)

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);

    tsc_ModesResult      SetTargetPrismConstant   (double newSetting);

    tsc_ModesResult      ClearTargetPrismConstant ();

    tsc_ModesResult      QueryTargetPrismConstant (tsc_QueryMode mode, double& result);

    tsc_ModesResult      SetTargetHeightMeasurementMethod     (x_Code newSetting);

    tsc_ModesResult      ClearTargetHeightMeasurementMethod   ();

    tsc_ModesResult      QueryTargetHeightMeasurementMethod   (tsc_QueryMode mode, x_Code& result);

 

Enumerations

tsc_ModesResult

enum tsc_ModesResult

{

    tsmr_Unspecified = 0,

    tsmr_Specified,

    tsmr_Supported,

    tsmr_Unsupported,

};

tsc_QueryMode

enum tsc_QueryMode

{

    tsqm_QueryThis = 0,

    tsqm_QueryInstrument,

    tsqm_QuerySupported

};

tsc_StationFace

enum tsc_StationFace

{

    tssf_Unspecify = -1,

    tssf_Unknown   =  0,   ///< Unknown face

    tssf_Face1,            ///< Face 1

    tssf_Face2             ///< Face 2

};

tsc_TsTracklightState

enum tsc_TsTracklightState

{

    tstl_Unspecify = -1,

    tstl_Off       =  0,  ///< Off

    tstl_LowOrSlow,       ///< Slow: Trimble SSeries/Trimble M3 (Low:  3600/5600/Leica).

    tstl_HighOrFast,      ///< Fast: Trimble SSeries/Trimble M3 (High: 3600/5600/Leica).

    tstl_TargetLocked,    ///< Flash when target is locked.

};

tsc_TsMeasureMode

enum tsc_TsMeasureMode

{

    tsmm_Unspecify = -1,

    tsmm_Fine,           ///< STD Instrument makes a single standard measurement.

    tsmm_Coarse,         ///< Not supported on S Series or SX10.

    tsmm_Tracking,       ///< TRK Instrument makes repeated tracking (coarse) measurements.

};

tsc_TsWorkingMode

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; 

}