tsc_PointStakeout
Overview
The images to the right are old, rather quaint, need to be replaced by something more current. They date back to the TSC3. Stakeout has moved on a little too.
Survey Core has a subsystem used for staking out objects, such as points, lines, and arcs. A user utilizes Stakeout to navigate to a target position defined by some database object. A stake or a mark is made to identify the position, which is then measured and stored as the as-staked point, along with deltas (differences in position) between the measured position and the target position.
The tsc_PointStakeout class is used to navigate to a target position defined by a database point and to control the measuring and storing process. Note that the term target position in this context is used to denote the point being navigated to, and is unrelated to the "target" used to denote the prism that is used with a total station.
Survey Core holds a single globally persistent stakeout list, which is a list of objects that the user has chosen to stake out. The tsc_PointStakeout class allows this list to either be used or bypassed. The stakeout list is stored in the current job.
There are four phases to the stakeout procedure:
User selects a point to be staked. The plugin may perform this process, or it may provide a list to the stakeout system which allows the user to edit the list and select points to be staked.
The user navigates to the point using the SC stakeout graphical display. Some aspects of this display may be controlled on the fly by the plugin, as indicated by the screen-snap to the right.
The user measures the as-staked position.
The as-staked position is stored in the database, along with other details such as various distances (deltas) between the target position and the measured position.
Starting a stakeout
Before a stakeout can be performed, there must be a currently open job and a running survey - either GNSS or conventional. The tsc_UITask within which the stakeout is being called must include these requirements.
When a stakeout is started from the API, the function does not return until the user either completes or aborts the stakeout.
A point stakeout may be started by supplying a single tsc_Point object. In this mode, the stakeout list remains unchanged and the stakeout system will go directly to the navigation screen, which consists of a graphical display and generally includes one or more arrows directing the user towards the target, as well as a number of textual values. The specific type of display depends on a number of factors including the type of instrument being used (conventional or GNSS), the capabilities of the instrument, and the distance from the target. Control returns to the plugin when the user completes staking out and storing the as-staked point, or exits the graphical stakeout screen.
Alternatively the stakeout may be started by supplying a list of points in a tsc_PointList. In such a case the current stakeout list is replaced by the supplied list, and the stakeout system displays the new list. This list may be edited by the user, and any entry from the list chosen for staking out. Once the point stakeout is finished the user is returned to the list where the next point may be chosen for staking. Control returns to the plugin when the user exits from the list or stakes the last point. The items in the stakeout list are persisted in the current job and are also indicated on the map with a small flag icon.
Options and settings
Stakeout has a large number of options and settings that affect its behaviour. These may be queried or changed in various places throughout the API. Because of the confusing nature of the various options, a there's a table of them all to describe their usage.
Public constructors
tsc_PointStakeout ();
Constructs the point stakeout object. This object contains virtual callback methods and may therefore not be copied. It should be always passed by reference.
Public methods
void StakeOutPoint (tsc_Point point);
This method starts a stakeout with just one point, and goes directly to the stakeout navigation display. The current stakeout list remains unchanged. When the user exits the graphical navigation screen, either directly or by storing the as-staked point, this method returns to the caller.
void StakeOutPoints ();
This method enters the stakeout system and displays the current stakeout list, which may be empty. Note that this list is persistent (stored in the job database), and may have come from a previous time that the job was opened. The user may add or remove points in the list, or stake them out. When the user exits the point list screen, this method returns to the caller.
void StakeOutPoints (tsc_PointList points);
Calling this method will remove all database entities from the current stakeout list and replace them with the supplied list of points. The stakeout system is entered and displays the new stakeout list, which may be empty. The user may add or remove points in the list, or stake them out. When the user exits the point list screen, this method returns to the caller. Note: If the list contains exactly one point, the list display step is skipped. Important: Arbitrarily replacing the user's stakeout list could be annoying.
bool IsStakeoutPossible ();
Returns true if SC is in a state where staking-out is possible. That is, a current job is open, and a survey with a suitable instrument is running.
Event handling
Most stakeout control is managed through the event handlers, which are called at various times throughout the staking-out process. Access and control is provided by interfaces passed to the event handler functions.
Event arguments
Every event passes an event arguments interface to the handler function. The handler uses this interface to obtain data about the current stakeout state and to control various aspects of its operation. There are a number of different event argument types for the different types of event, however most of them contain other common interface classes, such as tsc_PointStakeoutGetOptionsInterface or tsc_PointStakeoutNavInterface. These interfaces provide access to the current stakeout configuration and the current state of navigation respectively. Interfaces are provided for accessing and controlling stakeout options, as summarised on this page. The interfaces supplied in the event arguments parameter are valid only while control is inside the handler.Event handler methods
The handlers for required events must be be overridden; any that are not overridden will perform the default action. The default action may also be performed by calling the base class event handler (such as tsc_PointStakeout::OnInitialConfig), however in many cases the default action is simply to do nothing.
The handlers are presented below in the approximate order they would be called throughout the stakeout workflow.
void OnInitialConfig (tsc_PointStakeoutConfigFormEventArgs& eventArgs) override;
This event is raised immediately before the initial configuration form is displayed. This form allows the user to specify the stakeout method (To the point, From a point, Relative azimuth, etc), the GNSS antenna height, and other related items. The plugin may replace the standard form or supply initial values. The eventArgs also contains the tsc_PointStakeoutSetOptionsInterface, which allows stakeout options to be set.
A typical example of this form is shown to the right.
Note (for GNSS only) that if the plugin hides this form but no antenna height has been supplied, then the Antenna Height form is displayed instead, since stakeout cannot run without an antenna height.
void OnBeforeOptionsForm (tsc_PointStakeoutOptionsFormEventArgs& eventArgs) override;
This event handler is called just before the Options form is displayed. This form can be accessed by the user by pressing the Options softkey on the initial config form or while the navigation screen is displayed. Note that the options softkey can be hidden by an option in the tsc_PointStakeoutConfigFormEventArgs interface when the OnInitialConfig event is being handled; hiding the softkey means the OnBeforeOptionsForm event can never occur.
The OnBeforeOptionsForm handler may disable display of the options form. In this case the plugin should display its own replacement options form - otherwise the options softkey will appear to the user to do nothing.
void OnDrawTextFields (const tsc_PointStakeoutTextEventArgs& eventArgs) override;
Text drawing events are sent to this event handler. An event is generated every time there is a change in the user's current position or any other relevant variable, so that the text fields on the stakeout navigation screen may be updated in real-time. Since this function may be called many times per second, it must not perform lengthy calculations, never display UI, and not call any method which may cause a sleep or a wait.
The eventArgs parameter which is passed to the event handler contains configuration and navigation information as well as methods that are used to display information in the stakeout navigation text panel.
The screen-snap to the right shows the navigation display with three custom fields and a separator line.
virtual tsc_String OnAsStakedPointName (tsc_PointStakeoutMeasureEventArgs& eventArgs);
This handler is called when Survey Core first requires a name for the as-staked point. This is generally before the measure form is displayed, but may be at other times depending on the type of stakeout, various options, and the type of instrument. A point name must be returned. The point name that would have been used, automatically generated by Survey Core, can be obtained from eventArgs.
virtual tsc_String OnAsStakedFeatures (tsc_PointStakeoutMeasureEventArgs& eventArgs);
This handler is called when Survey Core first requires a feature code for the as-staked point. This is generally before the measure form is displayed, but may be at other times depending on the type of stakeout, various options, and the type of instrument. A feature code string must be returned. The eventArgs contains a method to obtain the automatically generated feature code string that would normally be used.
virtual tsc_String OnAsStakedStyleSheet (tsc_PointStakeoutStyleEventArgs& eventArgs);
This handler is invoked when a style sheet name is required, which will generally occur before the stake deltas form is displayed. The style sheet controls what is displayed on the stake deltas form. An empty string or a filename should be returned; if the file doesn't exist the user is warned and a default stylesheet used instead.
virtual void OnBeforePointMeasureForm (tsc_PointStakeoutMeasureEventArgs& eventArgs);
This event handler is called immediately before the as-staked point store form is displayed.
virtual void OnBeforePointDeltasForm (tsc_PointStakeoutStoreEventArgs& eventArgs);
This event handler is called before the point deltas form is displayed.
virtual void OnBeforePointStored (tsc_PointStakeoutStoreEventArgs& eventArgs);
This event handler is called shortly before the as-staked point is stored in the database.
virtual void OnDrawGraphics (tsc_PointStakeoutGraphicsEventArgs& eventArgs);
This event handler is called when the graphics portion of the stakeout window is being drawn. It allows additional graphics to be displayed. Because this function may be called often (up to several times per second), processing should be kept to a minimum.
Important: This event is generally only suitable for drawing text, since there are several different stakeout display modes, some of which may rotate according to the direction of travel. This means that the stakeout canvas azimuth (where the 'N' (North) arrow points) may vary, so any drawn graphics which represent a position would need to be rotated accordingly. Also, no scale value is provided, since this also only has a meaning in certain display modes.
Enumerations
The tsc_StakeoutTextOptions enumeration provides a small amount of control over text alignment and size. These options are used in conjunction with the tsc_PointStakeoutTextEventArgs class.