# STPointToCircularArc

STPointToCircularArc — Return a measured point by snapping provided point to the provided CircularString

Function Specification

```Function [lrs].[STPointToCircularArc] (
@p_circularString geometry,
@p_vertex         geometry,
@p_round_xy       int   = 3,
@p_round_zm       int   = 2
)
Returns geometry
```

Description

This function snaps supplied point to @p_circularString, returning the snapped point.

Computes Z and M values if exist on @p_circularString.

If input @p_circularString is 2D, length from start of @p_circularString to point is returned in M ordinate of snapped point.

Returned points ordinate values are rounded to @p_round_xy/@p_round_zm decimal digits of precision.

Notes

Supports CircularString geometries only.

If @p_point does not fall on CircularString, null is returned.

If @p_point is the same as the centre of the circle formed by the CircularString, the first point in the CircularString is returned.

Parameters

```    @p_circularString (geometry) - (Measured) CircularString with or without Z ordinates.
@p_point          (geometry) - Point near to linestring.
@p_round_xy            (int) - Decimal degrees of precision to which calculated XY ordinates are rounded.
@p_round_zm            (int) - Decimal degrees of precision to which calculated ZM ordinates are rounded.
```

Result

This function computes position of point on CircularString. If @p_point can’t be found on CircularArc, NULL is returned.

Examples

```select 'Point has relationship with XYZM circular arc' as test,
[lrs].[STPointToCircularArc] (
geometry::STGeomFromText('CIRCULARSTRING (3 6.325 -2.1 0, 0 7 -2.1 3.08, -3 6.325 -2.1 6.15)',0),
geometry::Point(2,8,0),
3,2).AsTextZM() as project_point
union all
select 'Point does not have relationship with XYM CircularSring' as test,
[lrs].[STPointToCircularArc] (
geometry::STGeomFromText('CIRCULARSTRING (3 6.325 NULL 0, 0 7 NULL 3.08, -3 6.325 NULL 6.15)',0),
geometry::Point(8,8,0),
3,2).AsTextZM() as project_point
union all
select 'Point is on centre of the circular arc' as test,
[lrs].[STPointToCircularArc] (
geometry::STGeomFromText('CIRCULARSTRING (3 6.3246 -1, 0 7 -1, -3 6.3246 -1)',0),
geometry::Point(0,0,0),
3,2).AsTextZM() as project_point
union all
select 'Point projects on to point half way along circular arc' as test,
[lrs].[STPointToCircularArc] (
geometry::STGeomFromText('CIRCULARSTRING (3 6.3246, 0 7, -3 6.3246)',0),
geometry::Point(0,3.5,0),
3,2).AsTextZM() as project_point
go

test                                                    project_point
------------------------------------------------------- -----------------------------
Point has relationship with XYZM circular arc           POINT (1.698 6.791 -2.1 1.37)
Point does not have relationship with XYM CircularSring NULL
Point is on centre of the circular arc                  POINT (3 6.3246 -1)
Point projects on to point half way along circular arc  POINT (0 7 NULL 3.1)
```