CircularString

Article
04/01/2012

A CircularString is a collection of zero or more continuous circular arc segments. A circular arc segment is a curved segment defined by three points in a two-dimensional plane; the first point cannot be the same as the third point. If all three points of a circular arc segment are collinear, the arc segment is treated as a line segment.

Important

For a detailed description and examples of the new spatial features in this release, including the CircularString subtype, download the white paper, New Spatial Features in SQL Server 2012.

CircularString instances

The drawing below shows valid CircularString instances:

5ff17e34-b578-4873-9d33-79500940d0bc

Accepted instances

A CircularString instance is accepted if it is either empty or contains an odd number of points, n, where n > 1. The following CircularString instances are accepted.

DECLARE @g1 geometry = 'CIRCULARSTRING EMPTY';
DECLARE @g2 geometry = 'CIRCULARSTRING(1 1, 2 0, -1 1)';
DECLARE @g3 geometry = 'CIRCULARSTRING(1 1, 2 0, 2 0, 2 0, 1 1)';

@g3 shows that CircularString instance may be accepted, but not valid. The following CircularString instance declaration is not accepted. This declaration throws a System.FormatException.

DECLARE @g geometry = 'CIRCULARSTRING(1 1, 2 0, 2 0, 1 1)';

Valid instances

A valid CircularString instance must be empty or have the following attributes:

It must contain at least one circular arc segment (that is, have a minimum of three points).
The last endpoint for each circular arc segment in the sequence, except for the last segment, must be the first endpoint for the next segment in the sequence.
It must have an odd number of points.
It cannot overlap itself over an interval.
Although CircularString instances may contain line segments, these line segments must be defined by three collinear points.

The following example shows valid CircularString instances.

DECLARE @g1 geometry = 'CIRCULARSTRING EMPTY';
DECLARE @g2 geometry = 'CIRCULARSTRING(1 1, 2 0, -1 1)';
DECLARE @g3 geometry = 'CIRCULARSTRING(1 1, 2 0, 2 0, 1 1, 0 1)';
DECLARE @g4 geometry = 'CIRCULARSTRING(1 1, 2 2, 2 2)';
SELECT @g1.STIsValid(), @g2.STIsValid(), @g3.STIsValid(),@g4.STIsValid();

A CircularString instance must contain at least two circular arc segments to define a complete circle. A CircularString instance cannot use a single circular arc segment (such as (1 1, 3 1, 1 1)) to define a complete circle. Use (1 1, 2 2, 3 1, 2 0, 1 1) to define the circle.

The following example shows CircularString instances that are not valid.

DECLARE @g1 geometry = 'CIRCULARSTRING(1 1, 2 0, 1 1)';
DECLARE @g2 geometry = 'CIRCULARSTRING(0 0, 0 0, 0 0)';
SELECT @g1.STIsValid(), @g2.STIsValid();

Instances with collinear points

In the following cases a circular arc segment will be treated as a line segment:

When all three points are collinear (for example, (1 3, 4 4, 7 5)).
When the first and middle point are the same, but the third point is different (for example, (1 3, 1 3, 7 5)).
When the middle and last point are the same, but the first point is different (for example, (1 3, 4 4, 4 4)).

Examples

A. Instantiating a Geometry Instance with an Empty CircularString

This example shows how to create an empty CircularString instance:

DECLARE @g geometry;
SET @g = geometry::Parse('CIRCULARSTRING EMPTY');

B. Instantiating a Geometry Instance Using a CircularString with One Circular Arc Segment

The following example shows how to create a CircularString instance with a single circular arc segment (half-circle):

DECLARE @g geometry;
SET @g = geometry:: STGeomFromText('CIRCULARSTRING(2 0, 1 1, 0 0)', 0);
SELECT @g.ToString();

C. Instantiating a Geometry Instance Using a CircularString with Multiple Circular Arc Segments

The following example shows how to create a CircularString instance with more than one circular arc segment (full circle):

DECLARE @g geometry;
SET @g = geometry::Parse('CIRCULARSTRING(2 1, 1 2, 0 1, 1 0, 2 1)');
SELECT 'Circumference = ' + CAST(@g.STLength() AS NVARCHAR(10));

This produces the following output:

Circumference = 6.28319

Compare the output when LineString is used instead of CircularString:

DECLARE @g geometry;
SET @g = geometry::STGeomFromText('LINESTRING(2 1, 1 2, 0 1, 1 0, 2 1)', 0);
SELECT 'Perimeter = ' + CAST(@g.STLength() AS NVARCHAR(10));

This produces the following output:

Perimeter = 5.65685

Notice that the value for the CircularString example is close to 2∏, which is the actual circumference of the circle.

D. Declaring and Instantiating a Geometry Instance with a CircularString in the Same Statement

This snippet shows how to declare and instantiate a geometry instance with a CircularString in the same statement:

DECLARE @g geometry = 'CIRCULARSTRING(0 0, 1 2.1082, 3 6.3246, 0 7, -3 6.3246, -1 2.1082, 0 0)';

E. Instantiating a Geography Instance with a CircularString

The following example shows how to declare and instantiate a geography instance with a CircularString:

DECLARE @g geography = 'CIRCULARSTRING(-122.358 47.653, -122.348 47.649, -122.348 47.658, -122.358 47.658, -122.358 47.653)';

F. Instantiating a Geometry Instance with a CircularString that is a Straight Line

The following example shows how to create a CircularString instance that is a straight line:

DECLARE @g geometry;
SET @g = geometry::STGeomFromText('CIRCULARSTRING(0 0, 1 2, 2 4)', 0);