|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface IBufferConstructionProperties
Provides access to members that control how sets of geometries are buffered.
This topic discusses how the properties exposed on the IBufferConstructionProperties interface affect the behavior of the buffering methods available on the IBufferConstruction interface.
The methods that actually generate geometric buffers, ConstructBuffers and ConstructBuffersByDistances, are implemented in IBufferConstruction. This interface also includes the compatibility method Buffer, which is intended for use by clients that want to replace their current useage of ITopologicalOperator::Buffer with a minimum of change to their code. Various ways of altering the default buffering behavior are implemented as properties in the interface IBufferConstructionProperties. The ConstructBuffers and ConstructBuffersByDistances methods make use of these properties. The Buffer method does not.
All buffering methods perform the buffering operation in the spatial reference of the first input geometry (the first element returned from a call to IEnumGeometry::Next). It may be the case that subsequent geometries are in different projections. In that case, Project will be applied to them. Of course, it will be more efficient to make sure that all geometries are in the same spatial reference before buffering them.
The properties on IBufferConstructionProperties modify the behavior of the Construct... methods and represent new buffering capabilities. The ends of the polylines can be buffered with either a square or round shape (EndOption), and the buffered polygon can cover an area to the right of the polyline (SideOption ), to the left, or both. Examples of these combinations are shown in Figure 1.
Figure 1 - Side type and end type options for P shape line
You can also specify the buffer distance in a distance unit different than that of the spatial reference of the input geometries (Unit). You can control the quality of the curve approximations used during buffer generation (DensifyDeviation ). Curved segments can optionally replace sequences of curve points, as shown in Figure 2 (GenerateCurves).
Figure 2 - Buffers without and with curved segments
You can specify multiple distance offsets for multiple sets of buffers around the same set of inputs (DistanceOffsets ), as shown in figure 3.
Figure 3 - Buffers at multiple distance offsets constructed around input geometries of different types (a point and a polygon in this example)
You can control whether or not generated buffers can be multi-part (ExplodeBuffers), whether or not overlaps between different buffers are preserved (UnionOverlappingBuffers), and if the buffer operation is cancellable and reports progress (BufferProgress). Figure 4 illustrates the ways in which the union and explode options work together.
Figure 4 - How the union and explode options determine the output geometries. There are two input geometries, each with two parts.
a. union overlaps = false, explode = false. There is one output geometry for each input geometry. Overlaps are preserved.
b. union overlaps = true, explode = false. One output geometry is produced for all input geometries and overlaps are dissolved.
c. union overlaps = true, explode = true. Overlaps are dissolved and one output geometry per separate area.
d. union overlaps = false, explode = true. One output geometry is produced for each input part. Overlaps are preserved.
You can create buffers that cover only the exterior of a polygon (OutsideOnly ), as shown in figure 5.
Figure 5 - polygon with only the outside covered by a buffer
Finally, you can buffer each input geometry by a different distance, either by implementing the IGeometricBufferSourceSink interface or by leveraging the default implementation of this interface provided by the BufferConstruction object (DistancesSource, GeometriesSource, GeometriesSink ).
| Method Summary | |
|---|---|
IBufferProgress |
getBufferProgress()
Report the progress of a buffer operation via this callback interface. |
double |
getDensifyDeviation()
The maximum distance between a line connecting two buffer curve points and the true curve (defaults to -1, indicating 1000 * xy tolerance of spatial reference of input geometries ). |
IDoubleArray |
getDistanceOffsets()
Constructs concentric buffers at the base distance plus each distance offset. |
int |
getEndOption()
Specifies the shape of the end caps of polyline buffers; defaults to 'esriBufferRound'. |
int |
getSideOption()
Specifies on which side of a polyline its buffer is constructed; defaults to 'esriBufferFull' (both sides). |
IUnit |
getUnit()
The unit of measure used for the buffering distance and densification deviation distance (optional, default units are obtained from spatial reference of input geometries). |
boolean |
isExplodeBuffers()
Specifies whether or not output buffers can have multiple outer rings (defaut is false). |
boolean |
isGenerateCurves()
Specifies whether sequences of curve points are replaced with true curves in the output buffers (default is true). |
boolean |
isOutsideOnly()
Excludes the inside of the input polygon from the output buffer (default = false). |
boolean |
isUnionOverlappingBuffers()
Specifies whether or not overlaps are preserved in the set of output buffers (default is false). |
void |
setBufferProgressByRef(IBufferProgress ppProgress)
Report the progress of a buffer operation via this callback interface. |
void |
setDensifyDeviation(double pDeviation)
The maximum distance between a line connecting two buffer curve points and the true curve (defaults to -1, indicating 1000 * xy tolerance of spatial reference of input geometries ). |
void |
setDistanceOffsetsByRef(IDoubleArray ppDistanceOffsets)
Constructs concentric buffers at the base distance plus each distance offset. |
void |
setEndOption(int pEndOption)
Specifies the shape of the end caps of polyline buffers; defaults to 'esriBufferRound'. |
void |
setExplodeBuffers(boolean pExplodeBuffers)
Specifies whether or not output buffers can have multiple outer rings (defaut is false). |
void |
setGenerateCurves(boolean pbGenerateCurves)
Specifies whether sequences of curve points are replaced with true curves in the output buffers (default is true). |
void |
setOutsideOnly(boolean bpOutsideOnly)
Excludes the inside of the input polygon from the output buffer (default = false). |
void |
setSideOption(int pSideOption)
Specifies on which side of a polyline its buffer is constructed; defaults to 'esriBufferFull' (both sides). |
void |
setUnionOverlappingBuffers(boolean pbUnionOverlapping)
Specifies whether or not overlaps are preserved in the set of output buffers (default is false). |
void |
setUnitByRef(IUnit ppUnit)
The unit of measure used for the buffering distance and densification deviation distance (optional, default units are obtained from spatial reference of input geometries). |
| Method Detail |
|---|
void setBufferProgressByRef(IBufferProgress ppProgress)
throws IOException,
AutomationException
ppProgress - A reference to a com.esri.arcgis.geometry.IBufferProgress (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
IBufferProgress getBufferProgress()
throws IOException,
AutomationException
ConstructBuffers and ConstructBuffersByDistances can report progress, if desired, during lengthy operations. Use this property to specify a callback interface that will receive progress events. This interface will also let clients cancel the current buffer method invocation. Buffer progress is measured in units of “operations”, “stages” and “steps”. An operation is either the action of buffering a group of geometries of the same dimension, or of dissolving together buffers generated from inputs of different dimensions. Each operation has one or more stages. Point buffering always has one stage. Polyline and polygon buffering may have multiple stages. Finally, each stage has several steps. Typically each step corresponds to some number of output buffers being generated, but this is not always the case.
Here are some examples.
1. Buffer 1000 points, without unioning the buffers. There is one operation, one stage and step progress will be reported for every n points buffered, where n is an implementation dependent parameter (every 10 points, say).
2. Buffer 1000 points with dissolve. There is 1 operation, 1 stage, and some number of steps, but in this case the steps correspond to progress made through both the buffering and dissolve operations, and thus do not correspond to individual points being buffered.
3. Buffer 500 points and 500 polygons, without dissolve. There are 2 operations. The polygon buffer operation may be subdivided into multiple stages depending on the buffer distance and complexity of the polygons encountered. Multiple stages mean that the buffers are “grown” incrementally. So for example, buffers at a distance of distance/3 are first generated, then those are rebuffered, etc. The number of stages may not be known in advance and could increase during the course of processing. The steps in each stage correspond to individual features being buffered.
4. 500 points and 500 polygons are buffered with dissolve. There are 3 operations, the final one being the dissolve operation. There may be multiple stages for the polygon buffering operation, depending on the buffer distance and how complicated the polygons are.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setDistanceOffsetsByRef(IDoubleArray ppDistanceOffsets)
throws IOException,
AutomationException
ppDistanceOffsets - A reference to a com.esri.arcgis.system.IDoubleArray (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
IDoubleArray getDistanceOffsets()
throws IOException,
AutomationException
ConstructBuffers and ConstructBuffersByDistances can generate multiple, concentric buffers around the same set of input geometries. This property is an array of distance values, specified in the units defined either by the spatial reference of the first input geometry or the Unit property. When this property is defined, each of its elements is added to the base distance specified by ConstructBuffers, or to the per-geometry distance used by ConstructBuffersByDistances. The following graphic shows the effect of specifying this property.
Example of multiple distance offsets and mixed dimension inputs when buffering. A point and a polygon have been buffered at 7 different distances, with the results at each distance unioned together.
Generation of buffers at each distance offset counts as a separate "operation" for the purposes of progress reporting. Refer to the BufferProgress property for more details on progress reporting.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setUnitByRef(IUnit ppUnit)
throws IOException,
AutomationException
ppUnit - A reference to a com.esri.arcgis.geometry.IUnit (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
IUnit getUnit()
throws IOException,
AutomationException
You can specify the buffer distance in a distance unit different than that of the spatial reference of the input geometries. The unit must be of the same type (angular or linear) as that of the input geometries' spatial reference.
See the geometry library overview for an example of using the units property to generate geodesic buffers around points.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setSideOption(int pSideOption)
throws IOException,
AutomationException
pSideOption - A com.esri.arcgis.geometry.esriBufferConstructionSideEnum constant (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
int getSideOption()
throws IOException,
AutomationException
When generating buffers for polylines, the buffered polygon can cover an area to the right of the polyline, to the left, or both. Here are some examples of these combinations.
Side type –end type options for P shape line: (a) left-flat, (b) right-flat, (c) full-flat, (d) left-round, (e) right-round, and (f) full-round. 
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setOutsideOnly(boolean bpOutsideOnly)
throws IOException,
AutomationException
bpOutsideOnly - The bpOutsideOnly (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
boolean isOutsideOnly()
throws IOException,
AutomationException
When buffering polygons, this property controls whether or not the constructed buffer covers only the outside of the polygon. Here is an example of an outside-only buffer.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setEndOption(int pEndOption)
throws IOException,
AutomationException
pEndOption - A com.esri.arcgis.geometry.esriBufferConstructionEndEnum constant (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
int getEndOption()
throws IOException,
AutomationException
When buffering polylines, this option controls the shape of the buffer area around the ends of the polylines. Here is an example of the different options.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setGenerateCurves(boolean pbGenerateCurves)
throws IOException,
AutomationException
pbGenerateCurves - The pbGenerateCurves (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
boolean isGenerateCurves()
throws IOException,
AutomationException
When buffers are constructed around polygons, straight line segments approximating curved parts of the buffer are generated. These sets of line segments can be replaced with single curve segments at the end of the buffering operation, if desired. You should use a small buffer deviation (see the DensifyDeviation property for details) when requesting that curves be stitched back into the output buffers. If a curve can not accurately replace its set of approximating line segments, no replacement will occur, even if this property is true. This could be the case when unioning overlaps between multiple buffers. Additionally, the buffering algorithm will sometimes “grow” buffers in stages (for example, buffer each feature by distance/3, then again, then again) in order to avoid creating very complicated intermediate results. When that happens, curves will not appear in the final version of that buffer.
Example of a buffered polygon with curves
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setDensifyDeviation(double pDeviation)
throws IOException,
AutomationException
pDeviation - The pDeviation (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
double getDensifyDeviation()
throws IOException,
AutomationException
Buffer construction uses sets of line segments to approximate curved parts of the buffer. You use the DensifyDeviation property to control how good this approximation is. It is the maximum distance, specified in the buffer distance units, between the approximating segment and the true curve.The smaller its value, the more segments will be required to approximate the curve. This will produce a more accurate buffer (particularly when unioning overlaps between buffers) but will take longer.
The first graphic shows a 1000 meter buffer created using a densify deviation of 1 meter.
The second graphic shows the same 1000 meter buffer created using a densify deviation of 0.1 meters.
When you wish to replace sets of buffer line segments with true curves (the GenerateCurves) property, you should use the smallest densify deviation that still produces acceptable performance, particularly in the case where you are unioning overlapping buffers together.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setUnionOverlappingBuffers(boolean pbUnionOverlapping)
throws IOException,
AutomationException
pbUnionOverlapping - The pbUnionOverlapping (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
boolean isUnionOverlappingBuffers()
throws IOException,
AutomationException
When buffering multiple input geometries, you can request that overlaps between individual buffers be unioned (or dissolved) together. The graphic below shows how this property and the ExplodeBuffers property work together.
How the union and explode options determine the output geometries. There are two input geometries, each with two parts.
a. union overlaps = false, explode = false. There is one output geometry for each input geometry. Overlaps are preserved.
b. union overlaps = true, explode = false. One output geometry is produced for all input geometries and overlaps are dissolved.
c. union overlaps = true, explode = true. Overlaps are dissolved and one output geometry per separate area.
d. union overlaps = false, explode= true. One output geometry is produced for each input part. Overlaps are preserved.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setExplodeBuffers(boolean pExplodeBuffers)
throws IOException,
AutomationException
pExplodeBuffers - The pExplodeBuffers (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
boolean isExplodeBuffers()
throws IOException,
AutomationException
You can produce separate buffer polygons for each connected buffer region. Such a polygon could contain nested rings (lakes) but not doubly nested rings (islands). The graphic below shows how the UnionOverlappingBuffers property works together with this property.
How the union and explode options determine the output geometries. There are two input geometries, each with two parts.
a. union overlaps = false, explode = false. There is one output geometry for each input geometry. Overlaps are preserved.
b. union overlaps = true, explode = false. One output geometry is produced for all input geometries and overlaps are dissolved.
c. union overlaps = true, explode = true. Overlaps are dissolved and one output geometry per separate area.
d. union overlaps = false, explode= true. One output geometry is produced for each input part. Overlaps are preserved.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||