tsc_Cogo

This is a class of static methods that are used in coordinate geometry calculations.  It is unrelated to the UI associated with the General Survey Cogo menu.

Static methods

In most cases two versions of each function are presented, one with and one without a tsc_CogoEnvironment.  If the environment is not supplied a default one will be used (which is normally only capable of cartesian grid calculations).  The use of the tsc_CogoEnvironment varies depending on the function.  Most functions will use the environment's coordinate system for coordinate transformation and the job for sourcing elements and points; the coordinate geometry settings are used to allow the user to set the coordinate framework for calculation.

Hypotenuse

static double CalculateHypotenuse (const double& x, const double& y);
static double CalculateHypotenuse (const double& x, const double& y, const double& z);
Calculates the square root of the sum of the squares in a cartesian framework, handles any double_Null argument with a double_Null return.

ArcTangent

static double CalculateArcTangent2 (const double& y, const double& x);
Calculates the atan2 of the values, and double_Null is handled. The return result is normalised between ± tsc_CogoConstants::Const_Pi. Useful for calculating the azimuth or vertical angle.

Calculate area

static tsc_AreaResults CalculateDbArea (tsc_EntityList& verticesInOrder);
static tsc_AreaResults CalculateDbArea (tsc_EntityList& verticesInOrder, const class tsc_CogoEnvironment& environment);
static double CalculateArea (tsc_EntityList& verticesInOrder, x_Code* error);
static double CalculateArea (tsc_EntityList& verticesInOrder, x_Code* error, const class tsc_CogoEnvironment& environment);
CalculateDbArea calculates the area in square meters enclosed by a polyline defined by the entity list, any discontinuity in the elements (such as the gap between points) will become a line and the figure will be self-closed back to the start element.

Lines and arcs are accepted and the figure may self-intersect (use the Compute & Subdivide Area functionality from the General Survey map to see this in action).  The enclosed area will be calculated but some complex shapes may not successfully calculate an area and will return double_Null.  The area value will be appropriately scaled for the coordinate framework (grid, ellipsoid, WGS84) specified by the environment's job correction settings.  Note that the tsc_CogoSettings will not be used for this function.  Source items in the entity list will be copied into the job specified in the environment (where the calculation will take place).

The supplied environment will specify which database holds the entities, in the case where no environment is passed in the current job will be used.

The supplied x_Code* error atgument may be nullptr if the caller does not care about error reasons.  

Calculate Average

static tsc_AverageResults CalculateDbAverage (class tsc_PointList& points);
static tsc_AverageResults CalculateDbAverage (class tsc_PointList& points, const class tsc_CogoEnvironment& environment);
Calculates the grid average ot the points in the supplied list.  Source items may be copied into the environment's job. Similarly to the area calculations, the tsc_CogoSettings will only be used to identify the database and the actual cogo environment will be that of the database.

Calculate Inverse

static tsc_Polar CalculateInverse (const tsc_CogoCoordinate&  from,
                                  const tsc_CogoCoordinate&  to);

static tsc_Polar CalculateInverse(const tsc_CogoCoordinate&  from,
                                  const tsc_CogoCoordinate&  to,
                                  const tsc_CogoEnvironment& environment);

Computes the inverse (distance and bearing) between two points in the frame of reference supplied in the tsc_CogoEnvironment.

static tsc_Polar CalculateInverse (const tsc_Local&        from,
  const tsc_Local&        to,
                                    const tsc_Ellipsoid&    environment);
Computes the inverse (distance and bearing) between two points on the supplied ellipsoid.

static tsc_InverseResults CalculateDbInverse (const class tsc_Point& from,
                                              const class tsc_Point& to);

static tsc_InverseResults CalculateDbInverse (const class tsc_Point& from,
                                              const class tsc_Point& to,
                                              const class tsc_CogoEnvironment& environment);

Do the same with database points, in this case the environment also specifies the job used to find the points and store the results.  Any passed-in tsc_CogoEnvironment must have the correct job set (not providing a tsc_CogoEnvironment indicates the current job).

static tsc_Grid FollowAzimuth (const tsc_CogoCoordinate&  start,
                              const tsc_Polar&           direction);

static tsc_Grid FollowAzimuth(const tsc_CogoCoordinate&  start,
                              const tsc_Polar&           direction,
                              const tsc_CogoEnvironment& environment);
Computes the end point given a start point, and an azimuth and distance. This is the complementary operation to CalcInverse above.

Distance along line

static tsc_StationOffset DistanceAlongLine (const tsc_CogoCoordinate&  lineStart,
                                            const tsc_CogoCoordinate&  lineEnd,
                                            const tsc_CogoCoordinate&  offLinePoint,
                                            const double&              startStation);

static tsc_StationOffset DistanceAlongLine (const tsc_CogoCoordinate&  lineStart,
                                            const tsc_CogoCoordinate&  lineEnd,
                                            const tsc_CogoCoordinate&  offLinePoint,
                                            const double&              startStation,
                                            const tsc_CogoEnvironment& environment);
Calculates the offsets of a given point from a line defined by a start and an end point.  The start point represents the origin of the offsets and may have a startStation false origin appended.

A startStation value of double_Null is considered the same as 0.0.  The offLinePoint may be located before or after the ends of the line, the offsets will be calculated as if the line extended to ±infinity.

Follow station and offset

static tsc_Grid FollowStationAndOffset (const tsc_CogoCoordinate&        lineStart,
                                        const tsc_CogoCoordinate&        lineEnd,
                                        const double&                    startStation,
                                        const tsc_StationOffset&         relativeToLine);

static tsc_Grid FollowStationAndOffset (const tsc_CogoCoordinate&        lineStart,
                                        const tsc_CogoCoordinate&        lineEnd,
                                        const double&                    startStation,
                                        const tsc_StationOffset&         relativeToLine,
                                        const class tsc_CogoEnvironment& environment);

Given a line defined by a start and an end point, calculates the point position on the (projected) line.

Compute Intersections

static tsc_Grid ProjectPointToLine (const tsc_CogoCoordinate&        lineStart,
                                    const tsc_CogoCoordinate&        lineEnd,
                                    const tsc_CogoCoordinate&        offLinePoint);

static tsc_Grid ProjectPointToLine (const tsc_CogoCoordinate&        lineStart,
                                    const tsc_CogoCoordinate&        lineEnd,
                                    const tsc_CogoCoordinate&        offLinePoint,
                                    const class tsc_CogoEnvironment& environment);
Given the offsets of a point from a line defined by a start and an end point, find the actual point position.

static void FourPointIntersection (const tsc_CogoCoordinate&        lineOneStart,
                                  const tsc_CogoCoordinate&        lineOneEnd,
                                  const tsc_CogoCoordinate&        lineTwoStart,
                                  const tsc_CogoCoordinate&        lineTwoEnd,
                                  tsc_CogoCoordinate&              result);

static void FourPointIntersection (const tsc_CogoCoordinate&        lineOneStart,
                                  const tsc_CogoCoordinate&        lineOneEnd,
                                  const tsc_CogoCoordinate&        lineTwoStart,
                                  const tsc_CogoCoordinate&        lineTwoEnd,
                                  const class tsc_CogoEnvironment& environment,
                                  tsc_CogoCoordinate&              result);

static tsc_Grid FourPointIntersection (const tsc_CogoCoordinate&        lineOneStart,
                                      const tsc_CogoCoordinate&        lineOneEnd,
                                      const tsc_CogoCoordinate&        lineTwoStart,
                                      const tsc_CogoCoordinate&        lineTwoEnd);

static tsc_Grid FourPointIntersection (const tsc_CogoCoordinate&        lineOneStart,
                                      const tsc_CogoCoordinate&        lineOneEnd,
                                      const tsc_CogoCoordinate&        lineTwoStart,
                                      const tsc_CogoCoordinate&        lineTwoEnd,
                                      const class tsc_CogoEnvironment& environment);
Given 4 points that define 2 lines that are not colinear or parallel, calculate the intersection.

static int CalculateDistanceDistanceIntersection (const tsc_CogoCoordinate&        pointOne,
                                                  const double&                    radiusOne,
                                                  const tsc_CogoCoordinate&        pointTwo,
                                                  const double&                    radiusTwo,
                                                  tsc_CogoCoordinate&              solutionOne,
                                                  tsc_CogoCoordinate&              solutionTwo);

static int CalculateDistanceDistanceIntersection (const tsc_CogoCoordinate&        pointOne,
                                                  const double&                    radiusOne,
                                                  const tsc_CogoCoordinate&        pointTwo,
                                                  const double&                    radiusTwo,
                                                  tsc_CogoCoordinate&              solutionOne,
                                                  tsc_CogoCoordinate&              solutionTwo,
                                                  const class tsc_CogoEnvironment& environment);
Given 2 points defining the center points of 2 circles of given independent radii, find the two intersections of the circles.

Returns the number of solutions:

• • 0 - Bad geometry (no overlap, cocyclic/concentric/etc or invalid input/double_Nulls).

  • 1 - Tangent touch intersect, both solutions identical => only solutionOne populated.

  • 2 - Two distinct solutions.

static int CalculateBearingDistanceIntersection(const tsc_CogoCoordinate&        lineStart,
                                                const tsc_CogoCoordinate&        lineEnd,
                                                const tsc_CogoCoordinate&        point,
                                                const double&                    radius,
                                                tsc_CogoCoordinate&              solutionOne,
                                                tsc_CogoCoordinate&              solutionTwo);

static int CalculateBearingDistanceIntersection(const tsc_CogoCoordinate&        lineStart,
                                                const tsc_CogoCoordinate&        lineEnd,
                                                const tsc_CogoCoordinate&        point,
                                                const double&                    radius,
                                                tsc_CogoCoordinate&              solutionOne,
                                                tsc_CogoCoordinate&              solutionTwo,
                                                const class tsc_CogoEnvironment& environment);
Given 2 points defining the a line and a third point associated with a given radius, find the two intersections of the circle and line.

Returns the number of solutions:

• • 0 - Bad geometry (no overlap, or invalid input/double_Nulls).

  • 1 - Tangent touch intersect, both solutions identical => only solutionOne populated.

  • 2 - Two distinct solutions.

Normalizing angles

static double NormaliseZeroToTwoPi (const double& value);
Reduces an angle to the range [ 0.0 <= angle < tsc_CogoConstants::Const_TwoPi ] 

static double NormaliseBetweenPi (const double& value);
Reduces an angle to the range [ -tsc_CogoConstants::Const_Pi <= angle < tsc_CogoConstants::Const_Pi ]

static double NormaliseBetweenPiByTwo (const double& value);
Reduces an angle to the range [ -tsc_CogoConstants::Const_PiOverTwo <= angle < tsc_CogoConstants::Const_PiOverTwo ]

Mathematical operations and double_Null

double_Null is a convenient placeholder value for an unknown value.  We suggest initializing any unknown double values to double_Null in the same manner you would initialize pointers to nullptr. The use of double_Null is not unlike NaN.

SurveyCore deals with double_Null inputs very well and the output to an operation that takes a double_Null value as a required input is... double_Null.

In this way the unknown value propagates through calculations and its unknown status is not lost or forgotten.

However there is a price to pay for this and that is that you must check for double_Null input values in your own calculations because the compiler will quite happily treat double_Null as data with no special consideration given.  It is quite easy to divide it by tsc_CogoConstants::Const_PiOver180 and end up with an overflow or number that is rubbish and is difficult to test for afterwards.

In short all relevant inputs should be checked prior to mathematical functions being called (+, -, /, *, sin, fabs...).