tsc_Point

A database point is represented by the tsc_Point class and is subclassed off tsc_Entity.  This class is lightweight and may be freely copied, although copies will always refer to the same object.  The point object may change as the database is updated, and may become non-existent if it is located in a linked job or csv file which is subsequently unlinked by the user.  

Changes only happen outside of the plugin, so a contiguous block of plugin code which doesn't perform any sort of wait or database update may safely access a point without concern over it changing or disappearing.  Because a tsc_Point is effectively a shared_ptr object should be defined and passed around as an instance, rather than a pointer or reference.

A point is typically obtained from a tsc_PointList or from the tsc_JobPoints object on a job. 

Database points always contain a position, which is stored in the most unprocessed form possible.  For instance, a total station measurement is stored as raw angles and an EDM distance, a GNSS point as a set of ECEF deltas from a GNSS base position, and a keyed-in grid coordinate as a grid.  The StoredType method returns the form in which the coordinate was stored.  Points may contain additional properties such as instrument and target or antenna information, to allow the stored position to be corrected and reduced to other forms.  The following classes represent the various coordinate types:

tsc_Grid
tsc_GridDeltas
tsc_Local
tsc_Wgs84
tsc_Ecef
tsc_EcefDeltas
tsc RawCircle
tsc_UnorientedCircle
tsc_CorrectedCircle

 "Best" points

Any number of identically named points may exist in an SC database.  Generally, only one of these will be used to supply the coordinate and other properties for the name, and this is known as the best point.  The algorithm used to determine the best point is somewhat complex and is documented in the General Survey help pages. Hidden points and deleted points are never considered as best points (tsc_PointMethod::tspm_MatchedPairHidden and tsc_PointMethod::tspm_MeanTurnedAngleHidden).

In brief, keyed-in control coordinates are best, topo points are better than staked-out points, deleted points are worst (or not considered at all) and so forth.  When points have equal quality, the oldest is considered best.  Points in the main job file are always better than identically-named points in linked files.

API functions allow you to select the best point of a group or find out if any given point is best.  The "bestness" of a point may change dynamically as the database changes or the user links or unlinks other files.

tsc_Point public methods

bool Exists () const;     (Inherited from tsc_Entity)
To determine if the point still exists use this method.  Points that are part of the main job file will always exist, points that are part of a linked job or csv file will cease to exist after the file is unlinked. Note that deleted points continue to exist, but have their deleted flag set.

tsc_Classification  Classification () const;
Returns the classification of the point.  For details, see the tsc_Classification enum. 

tsc_PointMethod Method () const;
Returns the method of the point.  For details, see the tsc_PointMethod enum. 

bool IsBest () const;
Determines if this point object is the best of all points of the same name.

bool IsDeleted () const;
Returns true if the point has been deleted.  Deleted points remain in the database; they are simply flagged as deleted and are not generally used or displayed.

tsc_String Name () const;     (Inherited from tsc_Entity)
Returns the name of the point.

tsc_String FeatureString () const;     (Inherited from tsc_Entity)
Returns the features of the point as a single string.  Attributes are not represented.  This string comes from the point's Code field.

tsc_String Notes () const;     (Inherited from tsc_Entity)
Returns the notes associated with this point.  The string may include line breaks, represented as "\r\n" (tsc_SurveyCore::NewLine).

Point coordinates

The point's coordinates can be obtained in a variety of different types.  If the requested type is different from the type of the coordinate in the database (as returned by StoredType), then some kind of coordinate transformation is applied which may be quite time-consuming - up to several seconds in extreme cases.  Some transformations may not be possible, and will return double_Null values for the elements of the coordinate that failed.

These calculations assume that the correct context (e.g. coordinate system, antenna height) can be found in the current job.  If you need to control the context further then use the coordinate subclass conversion methods directly as they will accept an environment argument (e.g. tsc_Wgs84::FromEcef()).

CalculateGrid obtains a copy of the grid coordinates for the point.  If the point's coordinate is not already a grid, it will be converted to one using the current coordinate system and settings from the job that contains the point.  Any or all of the resulting coordinate elements may be null.  The grid coordinate is often cached internally by Survey Core, so that subsequent references will be fast.

tsc_Grid CalculateGrid();
Obtains a copy of the WGS 84 coordinates for the point.  If the point's coordinate is not already WGS 84, it will be converted to one using the current coordinate system and settings from the job that contains the point.  Any or all of the resulting coordinate elements may be null.

tsc_Wgs84 CalculateWgs84();
This function returns the Local coordinate (ie, like the WGS-84 coordinate but on the Local ellipsoid) for the point.

tsc_Local CalculateLocal();
This function returns the ECEF coordinate for the point.

Prior to version 20.10:
Coordinate was calculated in terms of the current rover antenna phase center.  Requires a current GNSS survey.

From version 20.10 :
The ECEF coordinate is calculated using the database environment present when the point was stored, if such information is available (eg, a GPS measurement).

If there is no environment data, for example in the case of a keyed-in grid point, the current GNSS survey environment is used.

If neither is present a null position is returned.

tsc_Ecef CalculateEcef();
This function returns the ECEF deltas coordinate for the point, expressed as the deltas between phase centers of the current base and current rover antenna phase centers.  Requires a current GNSS RTK survey.

tsc_EcefDeltas CalculateEcefDeltas();
To obtain an equivalent raw total station observation, use this method.  If the coordinate was not originally stored as a Raw Circle within the current job's current environment (station, atmosphere, target) then an equivalent tsc_RawCircle is computed from the point's grid coordinate, using the current environment.  

If there is no current valid station (additionally empty stations cannot resolve coordinates) then the resulting raw circle will be empty; this will also be the case if the point location cannot be resolved (e.g. angles only observations).  A tsc_RawCircle is suitable for turning a total station to the point's position, by using methods from the tsc_TsModes class.  Do not use this call to retrieve original tsc_RawCircle observations; use the ObservedRawCircle method instead.  

See Coordinate types for a summary of types and the corrections and transformations that may be applied.

tsc_RawCircle CalculateRawCircle();

Measurement environment

Points may originate from a number of sources, and some of these sources provide additional information about how the coordinate was obtained.  This information is known as the environment. 

Survey Core always stores a measured coordinate in the form closest to that of the original measurement, and uses the environmental information to produce corrected values when required to do so.  For example, a total station measurement is stored as a RawCircle record which contains raw angles and the uncorrected EDM distance.  The environment may be applied to these values to provide more useful coordinates, such as a fully corrected polar coordinate from the station to the measured point, or a grid position.

TS Properties

tsc_Station Station () const;
For points measured by a total station, this method returns the station at the time the point was measured.  For any other type of measurement, an empty instance of tsc_Station is returned.

tsc_Target Target () const;
For points measured by a total station, this method returns the target at the time the point was measured.  For any other type of measurement, an empty instance of tsc_Target is returned.

tsc_TsEnvironment TsEnvironment () const;
For points measured by a total station, this method returns the environment (instrument, station, target, atmosphere, etc) at the time the point was measured.  For any other type of measurement, an empty instance of tsc_TsEnvironment is returned.

tsc_RawCircle ObservedRawCircle () const;
Use this call to retrieve the as-stored tsc_RawCircle.  This will return the actual observation if the point was stored this way and return an empty circle otherwise.  Note that this value may not be appropriate for issuing total station turn to commands as the environment (station, target, etc) may have changed since the measurement was taken.

void ObservedDistanceOffset (tsc_RawCircle&             circle,

                             double&                    leftRightOffset,

                             double&                    inOutOffset,

                             double&                    downUpOffset,

                             tsc_OffsetPerspectiveMode& displayOffsetPerspective) const;

Use this call to retrieve the as-stored raw distance-offset value, or empty value if the stored circle has no distance offset. Note that this may not be appropriate for the current station or target.

void ObservedAngleOffset (tsc_RawCircle&  firstCircle,
                          tsc_RawCircle&  secondCircle) const;

Use this call to retrieve the as-stored raw angle-offset value, or empty value if the stored circle has no angle offset. Note that this may not be appropriate for the current station or target.

GNSS Properties

tsc_GnssSurvey GnssSurvey () const;
For points measured by GNSS, this method returns the rover survey at the time the point was measured.  For any other type of measurement, an empty instance of tsc_GnssSurvey is returned.

tsc_GnssAntenna Antenna () const;
For points measured by GNSS, this method returns the rover antenna at the time the point was measured.  For any other type of measurement, an empty instance of tsc_GnssAntenna is returned.

tsc_GnssEnvironment GnssEnvironment () const;
For points measured by GNSS, this method returns the environment (survey, antenna, etc) at the time the point was measured.  For any other type of measurement, an empty instance of tsc_GnssEnvironment is returned.

tsc_GnssPrecisions GnssPrecisions() const;
For points measured by GNSS, this method returns the precisions and quality control at the time the point was measured.  For any other type of measurement, an empty instance of tsc_GnssPrecisions is returned.

tsc_Ecef ObservedEcef () const;
Use this call to retrieve the as-stored tsc_Ecef.  This will return the actual observation if the point was stored this way and return an empty coordinate otherwise.  Note that this value may not be appropriate for the currently running survey or antenna.

tsc_EcefDeltas ObservedEcefDeltas () const;
Use this call to retrieve the as-stored tsc_EcefDeltas.  This will return the actual observation if the point was stored this way and return an empty coordinate otherwise.  Note that this value may not be appropriate for the currently running survey or antenna. 

void ObservedEcefAtTiltedApc (tsc_Ecef& ecef, tsc_GnssTilt& tilt) const;
Use this call to retrieve the as-stored tsc_Ecef.  This will return the actual observation if the point was stored this way and return an empty coordinate otherwise.  Note that this value may not be appropriate for the currently running survey or antenna.  In particular these coordinates will not be directly above the measured point as the pole is deliberately tilted.

void ObservedEcefDeltasAtTiltedApc (tsc_EcefDeltas& ecefDeltas, tsc_GnssTilt& tilt) const;
Use this call to retrieve the as-stored tsc_EcefDeltas.  This will return the actual observation if the point was stored this way and return an empty coordinate otherwise.  Note that this value may not be appropriate for the currently running survey or antenna.  In particular these coordinates will not be directly above the measured point as the pole is deliberately tilted.

Residual Properties

tsc_GridDeltas ObservedStandardDeviation () const;
Get the result standard deviation.

int GetObservedResidualCount() const;
Retrieve the number of available residuals.

tsc_Residuals GetObservedResiduals(int index) const;
Retrieve the residuals at the index, may be empty for invalid indices.  The index should be from zero to the value returned by GetObservedResidualCount() less one.