Package com.esri.arcgisruntime.geometry

Class Part

  • All Implemented Interfaces:
    Iterable<Segment>, Collection<Segment>, List<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:
    CubicBezierSegment, EllipticArcSegment, LineSegment

    • Constructor Detail

      • 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:
        ImmutablePart

      • 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:
        ImmutablePart

      • 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,
            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 Detail

      • 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

      • 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

      • 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(int, Segment)

      • 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:
        add(Segment)

      • 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:
        size(), clear()

      • 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:
        size(), getPoints()

      • 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()

      • 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:
        getStartPoint()

      • 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:
        Geometry.hasCurves(), GeometryBuilder.hasCurves(), Segment.isCurve()

      • 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:
        PartCollection.getPartsAsPoints()

      • 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:
        add(int, Segment)

      • 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:
        isEmpty()