Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.geometry

Class Part

java.lang.Object
java.util.AbstractCollection<Segment>
java.util.AbstractList<Segment>
com.esri.arcgisruntime.geometry.Part
All Implemented Interfaces:
Iterable<Segment>, Collection<Segment>, List<Segment>, SequencedCollection<Segment>
public final class Part extends AbstractList<Segment>
Represents a mutable collection of Segments that define the shape of a part of a Multipart geometry under construction. Used in Polygon and Polyline constructors, and by MultipartBuilder.getParts() and MultipartBuilder.getParts() (both builders inherit from MultipartBuilder).

Use the methods inherited from the generic Java AbstractList<T> class to define and change the shape of the Part by adding, removing, or changing its segments. Additionally, the helper methods addPoint(), addPoints(), setPoint(), and removePoint() are all Point-based and allow working with points that represent the vertices of the Part, instead of working with segments.

Adjacent segments which share an end point and a start point are connected, and the shared vertex is not duplicated when accessing points. The Part can represent gaps between one end point and an adjacent start. However, this is only recommended as a temporary state while modifying a multipart builder; when using GeometryBuilder.toGeometry() the gaps are closed with line segments.

The SpatialReference of any geometries added to a Part must match that of the Part, or be null (in which case the geometry is assumed to have the same SpatialReference as the Part). Added geometries are not reprojected.

Parts can then be added to, inserted into, and removed from a PartCollection, in order to build up the complete shape of a geometry with multiple parts. Again, the SpatialReferences must be compatible.

Prior to v100.12, only LineSegment linear segments were available to be added to parts when building geometries. The SDK could display curved geometries, but you could not work with curves using the API; any curved segments in a geometry would be represented as LineSegments, and the curve information would be lost. You can call hasCurves() to determine if the part contains any curve segments.

From v100.12, geometry builders support curve segments. You can call hasCurves() to determine if the part contains any curve segments.

Since:
100.0.0
See Also:

  • Constructor Details

    • Part

      public Part(SpatialReference spatialReference)
      Creates a new empty Part with the given SpatialReference. SpatialReference cannot be changed after instantiation.
      Parameters:
      spatialReference - the SpatialReference of the new Part. May be null.
      Since:
      100.0.0

    • Part

      public Part(Iterable<Segment> segments)
      Creates a new part with the given set of Segments. The segments in the part can be modified after instantiation. The SpatialReference of the new Part will match that of the given segments.
      Parameters:
      segments - the set of Segments that this Part will be initialized with. For example, this argument may be an existing Part, ImmutablePart, or standard generic Java ArrayList containing Segments. If null, an empty Part is created.
      Throws:
      ArcGISRuntimeException - if segments contains Segments that have differing SpatialReferences set.
      Since:
      100.0.0
      See Also:

    • Part

      public Part(Iterable<Segment> segments, SpatialReference spatialReference)
      Creates a new part with the given set of Segments and SpatialReference. The segments in the part can be modified after instantiation.

      Use this constructor to create a new Part with a specific SpatialReference from an existing set of segments that have null SpatialReferences (the segments are assigned the given SpatialReference; they are not projected). Can also be used where the SpatialReference of some segments matches that of the argument, but is null for other segments.

      Parameters:
      segments - the set of Segments that this Part will be initialized with. For example, this argument may be an existing Part, ImmutablePart, or standard generic Java ArrayList containing Segments. If null, an empty Part is created.
      spatialReference - the SpatialReference of the new Part. May be null.
      Throws:
      ArcGISRuntimeException - if the segments argument contains Segments with SpatialReferences that do not match the spatialReference argument.
      Since:
      100.0.0
      See Also:

    • Part

      public Part(PointCollection points)
      Creates a new part from the given PointCollection. The part can be modified after instantiation. The SpatialReference of the new Part will match that of the given points.
      Parameters:
      points - the set of Points that this Part will be initialized with. If null, an empty Part is created.
      Since:
      100.0.0

    • Part

      public Part(PointCollection points, SpatialReference spatialReference)
      Creates a new part from the given PointCollection and SpatialReference. The part can be modified after instantiation.

      Use this constructor to create a new Part with a specific SpatialReference from an existing PointCollection that has a null SpatialReference (the points are assigned the given SpatialReference; they are not projected).

      Parameters:
      points - the set of Points that this Part will be initialized with. If null, an empty Part is created.
      spatialReference - the SpatialReference of the new Part. May be null.
      Throws:
      ArcGISRuntimeException - if the points argument contains Points with SpatialReferences that do not match the spatialReference argument.
      Since:
      100.0.0

    • Part

      public Part(ImmutablePointCollection points)
      Creates a new part from the given ImmutablePointCollection. The part can be modified after instantiation. The SpatialReference of the new Part will match that of the given points.

      Use this constructor to create a new Part from a Part of an existing Polygon or Polyline by using ImmutablePart.getPoints().

      Parameters:
      points - the set of Points that this Part will be initialized with
      Since:
      100.0.0

    • Part

      public Part(ImmutablePointCollection points, SpatialReference spatialReference)
      Creates a new part from the given ImmutablePointCollection and SpatialReference. The part can be modified after instantiation.

      Use this constructor to create a new Part with a specific SpatialReference from an existing ImmutablePointCollection that has a null SpatialReference (the points are assigned the given SpatialReference; they are not projected). An example of this is to create a new Part from a Part of an existing Polygon or Polyline by using ImmutablePart.getPoints().

      Parameters:
      points - the set of Points that this Part will be initialized with. If null, an empty Part is created.
      spatialReference - spatialReference the SpatialReference of the new Part. May be null.
      Since:
      100.0.0

  • Method Details

    • getSpatialReference

      public SpatialReference getSpatialReference()
      Gets the SpatialReference of the geometries in this Part. The SpatialReference defines how coordinates correspond to locations in the real world. This is set during instantiation and cannot be changed. May be null.
      Returns:
      the SpatialReference of the geometries in this Part
      Since:
      100.0.0

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Collection<Segment>
      Specified by:
      isEmpty in interface List<Segment>
      Overrides:
      isEmpty in class AbstractCollection<Segment>

    • contains

      public boolean contains(Object o)
      Specified by:
      contains in interface Collection<Segment>
      Specified by:
      contains in interface List<Segment>
      Overrides:
      contains in class AbstractCollection<Segment>

    • get

      public Segment get(int index)
      Gets a copy of the Segment at the given index position in this Part.
      Specified by:
      get in interface List<Segment>
      Specified by:
      get in class AbstractList<Segment>
      Parameters:
      index - the index of the Segment to copy
      Returns:
      a copy of the Segment at the given index
      Throws:
      IndexOutOfBoundsException - if index < 0 || index >= size()
      Since:
      100.0.0

    • size

      public int size()
      Returns the number of Segments in this Part. Use this to find the maximum index for calling get(int).

      A Part can also be represented by a set of Points representing each vertex; the getPointCount() method returns the number of Points in the Part. See getPointCount() for an explanation of how the two relate.

      Specified by:
      size in interface Collection<Segment>
      Specified by:
      size in interface List<Segment>
      Specified by:
      size in class AbstractCollection<Segment>
      Since:
      100.0.0
      See Also:

    • indexOf

      public int indexOf(Object o)
      Specified by:
      indexOf in interface List<Segment>
      Overrides:
      indexOf in class AbstractList<Segment>

    • set

      public Segment set(int index, Segment segment)
      Replaces the Segment at the given index position with the given Segment.

      Use this method to update a segment in a Part - as segments are immutable, properties of existing segments cannot be changed.

      Specified by:
      set in interface List<Segment>
      Overrides:
      set in class AbstractList<Segment>
      Parameters:
      index - the index of the Segment to replace
      segment - the Segment to set at the given index
      Throws:
      IndexOutOfBoundsException - if index < 0 || index >= size()
      NullPointerException - if segment is null
      ArcGISRuntimeException - if the segment has a SpatialReference that does not match that of this Part. The SpatialReference of the segment may however be null.
      Since:
      100.0.0
      See Also:

    • add

      public boolean add(Segment segment)
      Appends the given Segment to the end of this Part. If the start point of the segment matches the previous end point, the segment will share this point.

      The count of points will increase by 1 if the segment connects, or 2 points if it is disconnected.

      If the start point of the appended Segment is at a different location from the end point of the previous Segment, a gap will be introduced to the Part. Any gaps will be replaced by new connecting segments in the return value of GeometryBuilder.toGeometry().

      A more efficient way to add a LineSegment to a part is to use of the point addition methods. For example, addPoint(double, double).

      Specified by:
      add in interface Collection<Segment>
      Specified by:
      add in interface List<Segment>
      Overrides:
      add in class AbstractList<Segment>
      Parameters:
      segment - the Segment to append to this PointCollection
      Returns:
      always true
      Throws:
      NullPointerException - if segment is null
      ArcGISRuntimeException - if the segment has a SpatialReference that does not match that of this Part. The SpatialReference of the segment may however be null.
      Since:
      100.0.0
      See Also:

    • add

      public void add(int index, Segment segment)
      Inserts the given Segment at the given index position in this Part. The index positions of all existing Segments at that index or greater increase by one.

      If the start point and/or end point of the inserted Segment is at a different location to those of the adjacent Segments, gap(s) will be introduced to the Part. Any gaps will be replaced by new connecting segments in the return value of GeometryBuilder.toGeometry(). Alternatively, use the addPoint(int, Point) method to insert a Point in the Part.

      Specified by:
      add in interface List<Segment>
      Overrides:
      add in class AbstractList<Segment>
      Parameters:
      index - the index of the Segment to insert in the Part
      segment - the Segment to insert at the given index
      Throws:
      NullPointerException - if segment is null
      ArcGISRuntimeException - if the segment has a SpatialReference that does not match that of this Part. The SpatialReference of the segment may however be null.
      IndexOutOfBoundsException - if index < 0 || index > size()
      Since:
      100.0.0
      See Also:

    • remove

      public Segment remove(int index)
      Removes the Segment at the specified index position from this Part. No other segments are changed when this method is called, which may result in a gap between the segment ends.
      Specified by:
      remove in interface List<Segment>
      Overrides:
      remove in class AbstractList<Segment>
      Parameters:
      index - the index of the Segment to remove
      Returns:
      a copy of the removed Segment
      Throws:
      IndexOutOfBoundsException - if index < 0 || index >= size()
      Since:
      100.0.0
      See Also:

    • remove

      public boolean remove(Object o)
      Specified by:
      remove in interface Collection<Segment>
      Specified by:
      remove in interface List<Segment>
      Overrides:
      remove in class AbstractCollection<Segment>

    • removeAll

      public boolean removeAll(Collection<?> c)
      Specified by:
      removeAll in interface Collection<Segment>
      Specified by:
      removeAll in interface List<Segment>
      Overrides:
      removeAll in class AbstractCollection<Segment>

    • retainAll

      public boolean retainAll(Collection<?> c)
      Specified by:
      retainAll in interface Collection<Segment>
      Specified by:
      retainAll in interface List<Segment>
      Overrides:
      retainAll in class AbstractCollection<Segment>

    • getPointCount

      public int getPointCount()
      Returns the number of Points in the Part, representing the number of vertices in the shape. Use this to find the maximum index for calling getPoint(int).

      Typically this number is one greater than the number of Segments in the part (size()). Where two adjacent segments share a start and end location (there is no gap between the segments), this is represented by a single Point. If using point-based methods to construct Parts, there will be no gaps between segments. However if using Segments to construct Parts, it is possible to introduce gaps between segments.

      Gaps are eliminated when geometries are built using the GeometryBuilder.toGeometry() method. Completed Multipart geometries do not have gaps between the segments of a part, but separate Parts may be disjoint.

      Returns:
      the number of Points in the Part
      Since:
      100.0.0
      See Also:

    • getStartPoint

      public Point getStartPoint()
      Gets a copy of a Point representing the start of the first Segment of the Part. This is a shortcut to getting the first Segment in the Part, then getting its start point using Segment.getStartPoint(), or getting the first Point in the Part using getPoint(int).
      Returns:
      a Point representing the start point
      Since:
      100.0.0
      See Also:

    • getEndPoint

      public Point getEndPoint()
      Gets a copy of a Point representing the end of the last Segment of the Part. This is a shortcut to getting the last Segment in the Part, then getting its end point using Segment.getEndPoint(), or getting the last Point in the Part using getPoint(int).
      Returns:
      a Point representing the end point
      Since:
      100.0.0
      See Also:

    • hasCurves

      public boolean hasCurves()
      Indicates if this Part contains Segments that represent true curves.

      The ArcGIS system supports polygon and polyline geometries that contain curved segments in some types of data, for example geodatabases, feature services, and JSON.

      Prior to v100.12, only LineSegment linear segments were available to be added to parts when building geometries. The SDK could display curved geometries, but you could not work with curves using the API; any curved segments in a geometry would be represented as LineSegments, and the curve information would be lost. In editing workflows, use this method to determine if this Part contains curve information which would be lost if used in an editing workflow.

      From v100.12, geometry builders support curve segments. This method returns true if any segments where Segment.isCurve() is true have been added to the part.

      Returns:
      true if the part contains any curve segments; false otherwise
      Since:
      100.12.0
      See Also:

    • getPoints

      public Iterable<Point> getPoints()
      Gets an iterator of Points representing the ends of the Segments in this Part (the vertices in the shape).

      Where two adjacent segments share a start and end location (there is no gap between the segments), this is represented by a single Point. See getPointCount() for more information.

      Returns:
      an iterator of Points
      Since:
      100.0.0
      See Also:

    • getPoint

      public Point getPoint(int index)
      Gets a copy of the Point at the given index in the Part. Use getPointCount() to determine the maximum possible index. Note that points are copied, and therefore returned by-value.

      The vertices of a MultipartBuilder's current state can be represented as a series of Points, which can be accessed using this method, or by the getPoints() iterator. If the geometry contains curves, that information cannot be represented by points; segment-based methods such as get(int) and iterator() may be more appropriate instead. Note that at the current release, true curves are not supported.

      Parameters:
      index - the index of the Point to get
      Returns:
      a copy of the Point at the given index
      Throws:
      IndexOutOfBoundsException - if index < 0 || index >= getPointCount()
      Since:
      100.0.0

    • addPoint

      public void addPoint(Point point)
      Appends the given Point to the end of this Part, resulting in a new LineSegment between the previous last Point and the appended Point. This is a common method to use when building Multipart shapes without curves, as it may be simpler than using add(Segment) and creating Segments explicitly.

      Alternatives exist to append a new Point by specifying coordinates directly, using addPoint(double, double)) or similar overloads. Use the addPoint(int, Point) to insert a Point at a position other than the end of the Part.

      Parameters:
      point - the Point to append to this Part
      Throws:
      NullPointerException - if point is null
      ArcGISRuntimeException - if the point has a SpatialReference that does not match that of this Part. The SpatialReference of the point may however be null.
      Since:
      100.0.0

    • addPoint

      public void addPoint(double x, double y)
      Creates a new Point from the given x,y coordinates and appends it to the end of this Part, resulting in a new LineSegment between the previous last Point and the appended Point. This is a common method to use when building Multipart shapes without curves, as it may be simpler than using add(Segment) and creating Segments explicitly.

      The appended Point will have default z and m values, and will take on the spatial reference of the Part; therefore ensure that the x and y parameters are defined in the spatial reference of this Part. If either x or y are NaN, the added Point will be empty. Alternatively, append an existing Point object to a Part using addPoint(Point)).

      Parameters:
      x - the x coordinate of the new Point added to the Part
      y - the y coordinate of the new Point added to the Part
      Since:
      100.0.0

    • addPoint

      public void addPoint(double x, double y, double z)
      Creates a new Point from the given x,y coordinates and z value, and appends it to the end of this Part, resulting in a new LineSegment between the previous last Point and the appended Point. This is a common method to use when building Multipart shapes without curves, as it may be simpler than using add(Segment) and creating Segments explicitly.

      The appended Point will take on the spatial reference of the Part; therefore ensure that the x and y parameters are defined in the spatial reference of this Part. Alternatively, append an existing Point object to a Part using addPoint(Point)).

      Parameters:
      x - the x coordinate of the new Point added to the Part
      y - the y coordinate of the new Point added to the Part
      z - the z value of the new Point added to the Part
      Since:
      100.0.0

    • addPoints

      public void addPoints(Collection<? extends Point> points)
      Appends the given collection of Points to the end of this Part, resulting in new LineSegments between the previous last Point and each appended Point. This is a common method to use when building Multipart shapes without curves, as it may be simpler than using addAll(Collection) and creating Segments explicitly.
      Parameters:
      points - the collection of Points to append to the end of this Part
      Throws:
      NullPointerException - if points is null
      ArcGISRuntimeException - if the points have a SpatialReference that does not match that of this Part. The SpatialReference of the points may however be null.
      Since:
      100.0.0

    • addPoint

      public void addPoint(int index, Point point)
      Inserts the given Point at the given index position in this Part, by replacing an existing Segment with two new LineSegments. The index positions of all subsequent Segments (and Points) increase by one. Gaps between adjacent segments cannot be introduced by point-based methods, but existing gaps may be maintained; if affected segments already have a gap.

      Alternatively, use the addPoint(Point) method to append a Point to the end of the Part.

      Parameters:
      index - the index of the Point to insert in the Part
      point - the Point to insert at the given index
      Throws:
      NullPointerException - if point is null
      ArcGISRuntimeException - if the point has a SpatialReference that does not match that of this Part. The SpatialReference of the point may however be null.
      IndexOutOfBoundsException - if index < 0 || index > getPointCount()
      Since:
      100.0.0
      See Also:

    • addPoint

      public void addPoint(int index, double x, double y)
      Creates a new Point from the given x,y coordinates and inserts it at the given index position in this Part, by mreplacing an existing Segment with two new LineSegment. The index positions of all subsequent Segments (and Points) increase by one. Gaps between adjacent segments cannot be introduced by Point-based methods, but existing gaps may be maintained; if affected segments already have a gap.
      Parameters:
      index - the index of the Point to insert in the Part
      x - the x coordinate of the new Point inserted into the Part
      y - the y coordinate of the new Point inserted into the Part
      Throws:
      IndexOutOfBoundsException - if index < 0 || index > getPointCount()
      Since:
      100.0.0

    • addPoint

      public void addPoint(int index, double x, double y, double z)
      Creates a new Point from the given x,y coordinates and z value, and inserts it at the given index position in this Part, by replacing an existing Segment with two new LineSegments. The index positions of all subsequent Segments (and Points) increase by one. Gaps between adjacent segments cannot be introduced by Point-based methods, but existing gaps may be maintained; if affected segments already have a gap.
      Parameters:
      index - the index of the Point to insert in the Part
      x - the x coordinate of the new Point inserted into the Part
      y - the y coordinate of the new Point inserted into the Part
      z - the z value of the new Point inserted into the Part
      Throws:
      IndexOutOfBoundsException - if index < 0 || index > getPointCount()
      Since:
      100.0.0

    • addAllPoints

      public void addAllPoints(int index, Collection<? extends Point> points)
      Inserts the given collection of Points at the given index position in this Part. Up to two existing Segments may be removed and replaced by new LineSegments connecting to the new Points; additionally new LineSegments are created between each inserted Point. This is a common method to use when building Multipart shapes without curves, as it may be simpler than using addAll(int, Collection) and creating Segments explicitly.
      Parameters:
      index - the index position at which to begin inserting the points into the Part
      points - the collection of Points to insert at the given position
      Throws:
      NullPointerException - if points is null
      ArcGISRuntimeException - if any Point in points has a SpatialReference that does not match that of this Part. The SpatialReference of a Point may however be null.
      IndexOutOfBoundsException - if index < 0 || index > getPointCount()
      Since:
      100.0.0

    • setPoint

      public void setPoint(int index, Point point)
      Sets the given Point at the given point index position in this Part. This replaces the Point previously at that position and updates the segments that use it.

      The points in the part correspond to start and end points of segments. Setting a new point will affect 1 or 2 segments using the point at the specified index. The type of affected segment(s) (LineSegment, CubicBezierSegment or EllipticArcSegment) will remain the same.

      For affected cubic bezier segments, the shape of the curve may change because the control points remain the same, as does the unchanged start or end point location. For elliptic arc segments, the arc parameters are adjusted enough to ensure the unchanged start or end point location remains the same.

      Parameters:
      index - the index position within the Part at which to set the Point
      point - the Point to set
      Throws:
      IndexOutOfBoundsException - if index < 0 || index >= getPointCount()
      IllegalArgumentException - if point is null
      Since:
      100.3.0

    • removePoint

      public Point removePoint(int index)
      Removes the Point at the given index position from the Part. The two existing Segments that start and end at this Point are removed, and replaced by a new LineSegment that connects the adjacent Points.

      This is a common method to use when editing Multipart shapes without curves, as it may be simpler than working with Segments and using remove(int).

      Parameters:
      index - the index of the Point to remove from the Part
      Returns:
      a copy of the removed Point
      Throws:
      IndexOutOfBoundsException - if index < 0 || index >= getPointCount()
      Since:
      100.0.0

    • getSegmentIndexFromStartPointIndex

      public int getSegmentIndexFromStartPointIndex(int startPointIndex)
      Gets the index of the segment that has a given start point.
      Parameters:
      startPointIndex - the 0-based index of the start point
      Returns:
      the index of the segment, or -1 if startPointIndex does not correspond to a segment start point
      Throws:
      IndexOutOfBoundsException - if startPointIndex is out of bounds
      Since:
      100.1.0

    • getSegmentIndexFromEndPointIndex

      public int getSegmentIndexFromEndPointIndex(int endPointIndex)
      Gets the index of the segment that has a given end point.
      Parameters:
      endPointIndex - the 0-based index of the end point
      Returns:
      the index of the segment, or -1 if endPointIndex does not correspond to a segment end point
      Throws:
      IndexOutOfBoundsException - if endPointIndex is out of bounds
      Since:
      100.1.0

    • getStartPointIndexFromSegmentIndex

      public int getStartPointIndexFromSegmentIndex(int segmentIndex)
      Gets the index of the start point of a segment.
      Parameters:
      segmentIndex - the 0-based index of the segment
      Returns:
      the index of the start point
      Throws:
      IndexOutOfBoundsException - if segmentIndex is out of bounds
      Since:
      100.1.0

    • getEndPointIndexFromSegmentIndex

      public int getEndPointIndexFromSegmentIndex(int segmentIndex)
      Gets the index of the end point of a segment.
      Parameters:
      segmentIndex - the 0-based index of the segment
      Returns:
      the index of the end point
      Throws:
      IndexOutOfBoundsException - if segmentIndex is out of bounds
      Since:
      100.1.0

    • clear

      public void clear()
      Removes all Segments from the Part. Using this method is more efficient than removing all Segments individually.

      After calling this method, the Part will have a size() of zero. It will also have a getPointCount() of zero because the Points in a Part represent the ends of its current Segments.

      Specified by:
      clear in interface Collection<Segment>
      Specified by:
      clear in interface List<Segment>
      Overrides:
      clear in class AbstractList<Segment>
      Since:
      100.0.0
      See Also: