Export (0) Print
Expand All
Expand Minimize

STBuffer (geometry Data Type)

Returns a geometric object that represents the union of all points whose distance from a geometry instance is less than or equal to a specified value.

Applies to: SQL Server (SQL Server 2008 through current version), Azure SQL Database.

.STBuffer ( distance )

distance

Is a value of type float (double in the .NET Framework) specifying the distance from the geometry instance around which to calculate the buffer.

SQL Server return type: geometry

CLR return type: SqlGeometry

STBuffer() calculates a buffer like BufferWithTolerance, specifying tolerance = distance * .001 and relative = false.

When distance > 0 then either a Polygon or MultiPolygon instance is returned.

Note Note

Since distance is a float, a very small value can equate to zero in the calculations. When this occurs, a copy of the calling geometry instance is returned. See float and real (Transact-SQL)

When distance = 0, then a copy of the calling geometry instance is returned.

When distance < 0, then

  • an empty GeometryCollection instance is returned when the dimensions of the instance are 0 or 1.

  • a negative buffer is returned when the dimensions of the instance are 2 or more.

    Note Note

    A negative buffer may also create an empty GeometryCollection instance.

A negative buffer removes all points enclosed in given distance of the boundary of the geometry.

The error between the theorectical and computed buffer is max(tolerance, extents * 1.E-7) where tolerance = distance * .001. For more information on extents, see geometry Data Type Method Reference.

A. Calling STBuffer() with parameter_value < 0 on one dimensional geometry instance

The following example returns an empty GeometryCollection instance:

DECLARE @g geometry= 'LINESTRING(3 4, 8 11)';

SELECT @g.STBuffer(-1).ToString();

B. Calling STBuffer() with parameter_value < 0 on a Polygon instance

The following example returns a Polygon instance with a negative buffer:

DECLARE @g geometry = 'POLYGON((1 1, 1 5, 5 5, 5 1, 1 1))';

SELECT @g.STBuffer(-1).ToString();

C. Calling STBuffer() with parameter_value < 0 on a CurvePolygon instance

The following example returns a Polygon instance with a negative buffer from a CurvePolygon instance:

DECLARE @g geometry = 'CURVEPOLYGON(COMPOUNDCURVE(CIRCULARSTRING(0 4, 4 0, 8 4), (8 4, 0 4)))';

SELECT @g.STBuffer(-1).ToString();

Note Note

A Polygon instance is returned instead of a CurvePolygon instance. To return a CurvePolygon instance, see BufferWithCurves (geometry Data Type)

D. Calling STBuffer() with a negative parameter value that returns an empty instance

The following example shows what occurs when the distance parameter equals -2 for the previous example.

DECLARE @g geometry = 'CURVEPOLYGON(COMPOUNDCURVE(CIRCULARSTRING(0 4, 4 0, 8 4), (8 4, 0 4)))';

SELECT @g.STBuffer(-2).ToString();

This SELECT statement returns a GEOMETRYCOLLECTION EMPTY.

E. Calling STBuffer() with parameter_value = 0

The following example returns a copy of the calling geometry instance:

DECLARE @g geometry = 'LINESTRING(3 4, 8 11)';

SELECT @g.STBuffer(0).ToString();

F. Calling STBuffer() with a non-zero parameter value that is extremely small

The following example also returns a copy of the calling geometry instance:

DECLARE @g geometry = 'LINESTRING(3 4, 8 11)';

DECLARE @distance float = 1e-20;

SELECT @g.STBuffer(@distance).ToString();

G. Calling STBuffer() with parameter_value > 0

The following example returns a Polygon instance:

DECLARE @g geometry= 'LINESTRING(3 4, 8 11)';

SELECT @g.STBuffer(2).ToString();

H. Calling STBuffer() with a string parameter value

The following example returns the same Polygon instance as mentioned earlier, but a string parameter is passed to the method:

DECLARE @g geometry= 'LINESTRING(3 4, 8 11)';

SELECT @g.STBuffer('2').ToString();

The following example will throw an error:

DECLARE @g geometry = 'LINESTRING(3 4, 8 11)';

SELECT @g.STBuffer('a').ToString();

Note Note

The previous two examples passed a string literal to the STBuffer(). The first example works because the string literal can be converted to a numeric value. However, the second example throws an ArgumentException.

I. Calling STBuffer() on a MultiPoint instance

The following example returns two MultiPolygon instances and one Polygon instance:

DECLARE @g geometry = 'MULTIPOINT((1 1),(1 4))';

SELECT @g.STBuffer(1).ToString();

SELECT @g.STBuffer(1.5).ToString();

SELECT @g.STBuffer(1.6).ToString();

The first two SELECT statements return a MultiPolygon instance because the parameter distance is less than or equal to 1/2 the distance between the two points (1 1) and (1 4). The third SELECT statement returns a Polygon instance because the buffered instances of the two points (1 1) and (1 4) overlap.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft