From 6f28076f2bf2582f340d7d6ac96e4b78f215b26f Mon Sep 17 00:00:00 2001 From: Oliver Snowden Date: Sat, 10 Oct 2015 23:38:37 +0100 Subject: [PATCH] Java 8 compliant Javadoc http://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#BEJEFABE --- .../com/esri/core/geometry/BucketSort.java | 5 +- .../esri/core/geometry/CombineOperator.java | 26 +- .../com/esri/core/geometry/ConvexHull.java | 39 +- .../java/com/esri/core/geometry/Envelope.java | 16 +- .../com/esri/core/geometry/Envelope1D.java | 6 + .../com/esri/core/geometry/Envelope2D.java | 131 +++- .../geometry/Envelope2DIntersectorImpl.java | 6 +- .../java/com/esri/core/geometry/Geometry.java | 130 ++-- .../esri/core/geometry/GeometryCursor.java | 49 +- .../esri/core/geometry/GeometryEngine.java | 598 +++++++++++------- .../esri/core/geometry/IntervalTreeImpl.java | 66 +- .../com/esri/core/geometry/JsonCursor.java | 33 +- .../com/esri/core/geometry/MapGeometry.java | 4 +- .../com/esri/core/geometry/MathUtils.java | 6 +- .../com/esri/core/geometry/MultiPath.java | 316 +++++---- .../core/geometry/MultiVertexGeometry.java | 199 ++++-- .../java/com/esri/core/geometry/Operator.java | 23 +- .../esri/core/geometry/OperatorBuffer.java | 72 ++- .../com/esri/core/geometry/OperatorClip.java | 60 +- .../com/esri/core/geometry/OperatorCut.java | 31 +- .../geometry/OperatorDensifyByLength.java | 86 +-- .../core/geometry/OperatorDifference.java | 82 ++- .../esri/core/geometry/OperatorDistance.java | 39 +- .../core/geometry/OperatorExportToJson.java | 27 +- .../core/geometry/OperatorExportToWkb.java | 70 +- .../esri/core/geometry/OperatorFactory.java | 27 +- .../core/geometry/OperatorFactoryLocal.java | 2 +- .../core/geometry/OperatorGeneralize.java | 29 +- .../geometry/OperatorImportFromGeoJson.java | 86 ++- .../core/geometry/OperatorImportFromJson.java | 50 +- .../core/geometry/OperatorImportFromWkb.java | 68 +- .../core/geometry/OperatorImportFromWkt.java | 74 ++- .../core/geometry/OperatorIntersection.java | 137 ++-- .../esri/core/geometry/OperatorOffset.java | 134 ++-- .../core/geometry/OperatorProximity2D.java | 82 ++- .../esri/core/geometry/OperatorRelate.java | 32 +- .../core/geometry/OperatorSimpleRelation.java | 54 +- .../esri/core/geometry/OperatorSimplify.java | 106 +++- .../core/geometry/OperatorSimplifyOGC.java | 85 ++- .../geometry/OperatorSymmetricDifference.java | 72 ++- .../com/esri/core/geometry/OperatorUnion.java | 65 +- .../java/com/esri/core/geometry/Point.java | 23 +- .../java/com/esri/core/geometry/Point2D.java | 32 +- .../java/com/esri/core/geometry/Polygon.java | 70 +- .../java/com/esri/core/geometry/Polyline.java | 11 +- .../esri/core/geometry/ProgressTracker.java | 41 +- .../esri/core/geometry/Proximity2DResult.java | 10 +- .../java/com/esri/core/geometry/QuadTree.java | 129 ++-- .../com/esri/core/geometry/QuadTreeImpl.java | 160 +++-- .../core/geometry/RasterizedGeometry2D.java | 49 +- .../java/com/esri/core/geometry/Segment.java | 241 ++++--- .../esri/core/geometry/SegmentIterator.java | 46 +- .../esri/core/geometry/SimpleRasterizer.java | 45 +- .../esri/core/geometry/Transformation2D.java | 320 +++++----- .../esri/core/geometry/VertexDescription.java | 101 +-- .../esri/core/geometry/ogc/OGCGeometry.java | 16 +- .../geometry/ogc/OGCGeometryCollection.java | 8 +- .../esri/core/geometry/ogc/OGCLineString.java | 8 +- .../esri/core/geometry/ogc/OGCMultiPoint.java | 8 +- .../esri/core/geometry/ogc/OGCPolygon.java | 2 +- 60 files changed, 2928 insertions(+), 1615 deletions(-) diff --git a/src/main/java/com/esri/core/geometry/BucketSort.java b/src/main/java/com/esri/core/geometry/BucketSort.java index 5039a4e8..c2a6899e 100644 --- a/src/main/java/com/esri/core/geometry/BucketSort.java +++ b/src/main/java/com/esri/core/geometry/BucketSort.java @@ -137,7 +137,7 @@ public void sort(AttributeStreamOfInt32 indices, int begin, int end, * @param capacity * - the number of elements to sort (-1 if not known). The * bucket_count are usually equal. - * @return Returns False, if the bucket sort cannot be used with the given + * @return {@code false} if the bucket sort cannot be used with the given * parameters. The method also can throw out of memory exception. In * the later case, one should fall back to the regular sort. */ @@ -159,6 +159,7 @@ private boolean reset(int bucket_count, double min_value, double max_value, } /** + * TODO * Adds new element to the bucket builder. The value must be between * min_value and max_value. * @@ -175,7 +176,7 @@ private int getBucket(double value) { } /** - * Returns the bucket count. + * @return the bucket count. */ private int getBucketCount() { return m_buckets.size(); diff --git a/src/main/java/com/esri/core/geometry/CombineOperator.java b/src/main/java/com/esri/core/geometry/CombineOperator.java index 43e5ac2c..4c52a4ee 100644 --- a/src/main/java/com/esri/core/geometry/CombineOperator.java +++ b/src/main/java/com/esri/core/geometry/CombineOperator.java @@ -36,13 +36,25 @@ public interface CombineOperator { * Operation on two geometries, returning a third. Examples include * Intersection, Difference, and so forth. * - * @param geom1 and geom2 are the geometry instances to be operated on. - * @param sr The spatial reference to get the tolerance value from. - * When sr is null, the tolerance is calculated from the input geometries. - * @param progressTracker ProgressTracker instance that is used to cancel the lengthy operation. Can be null. - * @return Returns the result geoemtry. In some cases the returned value can point to geom1 or geom2 - * instance. For example, the OperatorIntersection may return geom2 when it is completely - * inside of the geom1. + * @param geom1 + * the first geometry of the parameter pair to be operated on. + * + * @param geom2 + * the second geometry of the parameter pair to be operated on. + * + * @param sr + * The spatial reference to get the tolerance value from. + * When sr is null, the tolerance is calculated from the input + * geometries. + * + * @param progressTracker + * ProgressTracker instance that is used to cancel the lengthy + * operation. Can be null. + * + * @return the result geoemtry. In some cases the returned value can point + * to geom1 or geom2 instance. For example, the + * OperatorIntersection may return geom2 when it is completely + * inside of the geom1. */ public Geometry execute(Geometry geom1, Geometry geom2, SpatialReference sr, ProgressTracker progressTracker); diff --git a/src/main/java/com/esri/core/geometry/ConvexHull.java b/src/main/java/com/esri/core/geometry/ConvexHull.java index bafe51e0..b07e1849 100644 --- a/src/main/java/com/esri/core/geometry/ConvexHull.java +++ b/src/main/java/com/esri/core/geometry/ConvexHull.java @@ -53,8 +53,10 @@ private ConvexHull(Point2D[] points) { /** * Adds a geometry to the current bounding geometry using an incremental - * algorithm for dynamic insertion. \param geometry The geometry to add to - * the bounding geometry. + * algorithm for dynamic insertion. + * + * @param geometry + * The geometry to add to the bounding geometry. */ void addGeometry(Geometry geometry) { @@ -96,8 +98,10 @@ Geometry getBoundingGeometry() { /** * Static method to construct the convex hull of a Multi_vertex_geometry. - * Returns a Polygon. \param mvg The geometry used to create the convex - * hull. + * Returns a Polygon. + * + * @param mvg + * The geometry used to create the convex hull. */ static Polygon construct(MultiVertexGeometry mvg) { @@ -157,10 +161,17 @@ static Polygon construct(MultiVertexGeometry mvg) { * Static method to construct the convex hull from an array of points. The * out_convex_hull array will be populated with the subset of index * positions which contribute to the convex hull. Returns the number of - * points in the convex hull. \param points The points used to create the - * convex hull. \param count The number of points in the input Point2D - * array. \param out_convex_hull An index array allocated by the user at - * least as big as the size of the input points array. + * points in the convex hull. + * + * @param points + * The points used to create the convex hull. + * + * @param count + * The number of points in the input Point2D array. + * + * @param out_convex_hull + * An index array allocated by the user at least as big as the size + * of the input points array. TODO */ static int construct(Point2D[] points, int count, int[] bounding_geometry) { ConvexHull convex_hull = new ConvexHull(points); @@ -199,10 +210,14 @@ static int construct(Point2D[] points, int count, int[] bounding_geometry) { } /** - * Returns true if the given path of the input MultiPath is convex. Returns - * false otherwise. \param multi_path The MultiPath to check if the path is - * convex. \param path_index The path of the MultiPath to check if its - * convex. + * @param multi_path + * The MultiPath to check if the path is convex. + * + * @param path_index + * The path of the MultiPath to check if its convex. + * + * @return {@code true} if the given path of the input MultiPath is convex. + * Return {@code false} otherwise. */ static boolean isPathConvex(MultiPath multi_path, int path_index, ProgressTracker progress_tracker) { diff --git a/src/main/java/com/esri/core/geometry/Envelope.java b/src/main/java/com/esri/core/geometry/Envelope.java index 6991f26e..d327a171 100644 --- a/src/main/java/com/esri/core/geometry/Envelope.java +++ b/src/main/java/com/esri/core/geometry/Envelope.java @@ -958,9 +958,11 @@ public Point getUpperLeft() { /** * Checks if this envelope contains (covers) the specified point. * - * @param p - * The Point to be tested for coverage. - * @return TRUE if this envelope contains (covers) the specified point. + * @param p + * The Point to be tested for coverage. + * + * @return {@code true} if this envelope contains (covers) the specified + * point. */ public boolean contains(Point p) { if (p.isEmpty()) @@ -971,9 +973,11 @@ public boolean contains(Point p) { /** * Checks if this envelope contains (covers) other envelope. * - * @param env - * The envelope to be tested for coverage. - * @return TRUE if this envelope contains (covers) the specified envelope. + * @param env + * The envelope to be tested for coverage. + * + * @return {@code true} if this envelope contains (covers) the specified + * envelope. */ public boolean contains(Envelope env) { return m_envelope.contains(env.m_envelope); diff --git a/src/main/java/com/esri/core/geometry/Envelope1D.java b/src/main/java/com/esri/core/geometry/Envelope1D.java index 9e30e08b..2aad949b 100644 --- a/src/main/java/com/esri/core/geometry/Envelope1D.java +++ b/src/main/java/com/esri/core/geometry/Envelope1D.java @@ -125,6 +125,12 @@ public boolean contains(double v) { /** * Returns True if the envelope contains the other envelope (boundary * inclusive). Note: Will return false if either envelope is empty. + * + * @param other + * the envelope to be tested for coverage. + * + * @return {@code true} if this envelope contains (covers) the specified + * envelope. */ public boolean contains(/* const */Envelope1D other) /* const */ { diff --git a/src/main/java/com/esri/core/geometry/Envelope2D.java b/src/main/java/com/esri/core/geometry/Envelope2D.java index 3b9a02f7..2707c7cf 100644 --- a/src/main/java/com/esri/core/geometry/Envelope2D.java +++ b/src/main/java/com/esri/core/geometry/Envelope2D.java @@ -114,6 +114,9 @@ public Envelope2D getInflated(double dx, double dy) { /** * Sets the envelope from the array of points. The envelope will be set to * empty if the array is null. + * + * @param points + * to define this envelope */ public void setFromPoints(Point2D[] points) { if (points == null || points.length == 0) { @@ -181,6 +184,12 @@ else if (ymax < y) /** * Merges a point with this envelope without checking if the envelope is * empty. Use with care. + * + * @param x + * TODO + * + * @param y + * TODO */ public void mergeNE(double x, double y) { if (xmin > x) @@ -240,8 +249,12 @@ public void zoom(double factorX, double factorY) { } /** - * Checks if this envelope intersects the other. - * @return True if this envelope intersects the other. + * Checks if this envelope intersects the other. + * + * @param other + * the envelope to be tested for intersection. + * + * @return {@code true} if this envelope intersects the other. */ public boolean isIntersecting(Envelope2D other) { return !isEmpty() @@ -257,9 +270,12 @@ public boolean isIntersecting(Envelope2D other) { } /** - * Checks if this envelope intersects the other assuming neither one is empty. - * @return True if this envelope intersects the other. Assumes this and - * other envelopes are not empty. + * Checks if this envelope intersects the other assuming neither one is empty. + * + * @param other + * the envelope to be tested for intersection. + * @return {@code true} if this envelope intersects the other. Assumes this + * and other envelopes are not empty. */ public boolean isIntersectingNE(Envelope2D other) { return ((xmin <= other.xmin) ? xmax >= other.xmin : other.xmax >= xmin) @@ -274,9 +290,11 @@ public boolean isIntersectingNE(Envelope2D other) { /** * Intersects this envelope with the other and stores result in this * envelope. - * - * @return True if this envelope intersects the other, otherwise sets this - * envelope to empty state and returns False. + * + * @param other the envelope to be tested for intersection. + * + * @return {@code true} if this envelope intersects the other, otherwise + * sets this envelope to empty state and returns {@code false}. */ public boolean intersect(Envelope2D other) { if (isEmpty() || other.isEmpty()) @@ -303,15 +321,16 @@ public boolean intersect(Envelope2D other) { } /** - * Queries a corner of the envelope. - * - * @param index Indicates a corner of the envelope. - *

0 => lower left or (xmin, ymin) - *

1 => upper left or (xmin, ymax) - *

2 => upper right or (xmax, ymax) - *

3 => lower right or (xmax, ymin) - * @return Point at a corner of the envelope. - * + * Queries a corner of the envelope. + *

{@literal 0 => lower left or (xmin, ymin)} + *

{@literal 1 => upper left or (xmin, ymax)} + *

{@literal 2 => upper right or (xmax, ymax)} + *

{@literal 3 => lower right or (xmax, ymin)} + * + * @param index + * Indicates a corner of the envelope. + * + * @return Point at a corner of the envelope. */ public Point2D queryCorner(int index) { switch (index) { @@ -332,6 +351,9 @@ public Point2D queryCorner(int index) { /** * Queries corners into a given array. The array length must be at least * 4. Starts from the lower left corner and goes clockwise. + * + * @param corners + * an array for insertion of envelope points */ public void queryCorners(Point2D[] corners) { if ((corners == null) || (corners.length < 4)) @@ -361,6 +383,9 @@ public void queryCorners(Point2D[] corners) { * Queries corners into a given array in reversed order. The array length * must be at least 4. Starts from the lower left corner and goes * counterclockwise. + * + * @param corners + * an array for insertion of envelope points */ public void queryCornersReversed(Point2D[] corners) { if (corners == null || ((corners != null) && (corners.length < 4))) @@ -462,6 +487,12 @@ public double getHeight() { /** * Moves the Envelope by given distance. + * + * @param dx + * the delta for movement in the X direction + * + * @param dy + * the delta for movement in the Y direction */ public void move(double dx, double dy) { if (isEmpty()) @@ -518,8 +549,8 @@ public void queryUpperRight(Point2D pt) { } /** - * Returns True if this envelope is valid (empty, or has xmin less or equal - * to xmax, or ymin less or equal to ymax). + * @return {@code true} if this envelope is valid (empty, or has xmin less + * or equal to xmax, or ymin less or equal to ymax). */ public boolean isValid() { return isEmpty() || (xmin <= xmax && ymin <= ymax); @@ -581,8 +612,11 @@ public boolean contains(double x, double y) { } /** - * Returns True if the envelope contains the other envelope (boundary - * inclusive). + * @param other + * the envelope to be tested for containment. + * + * @return {@code true} if the envelope contains the other envelope + * (boundary inclusive). */ public boolean contains(Envelope2D other) {// Note: Will return False, if // either envelope is empty. @@ -591,7 +625,14 @@ public boolean contains(Envelope2D other) {// Note: Will return False, if } /** - * Returns True if the envelope contains the point (boundary exclusive). + * @param x + * coordinate of point for containment calculation + * + * @param y + * coordinate of point for containment calculation + * + * @return {@code true} if the envelope contains the point (boundary + * exclusive). */ public boolean containsExclusive(double x, double y) { // Note: This will return False, if envelope is empty, thus no need to @@ -600,15 +641,19 @@ public boolean containsExclusive(double x, double y) { } /** - * Returns True if the envelope contains the point (boundary exclusive). + * @param pt + * the query parameter for containment operation + * + * @return {@code true} if the envelope contains the point (boundary + * exclusive). */ public boolean containsExclusive(Point2D pt) { return containsExclusive(pt.x, pt.y); } /** - * Returns True if the envelope contains the other envelope (boundary - * exclusive). + * @return {@code true} if the envelope contains the other envelope + * (boundary exclusive). */ boolean containsExclusive(Envelope2D other) { // Note: This will return False, if either envelope is empty, thus no @@ -1011,8 +1056,12 @@ boolean clipLineAuxiliary(double denominator, double numerator, } /** - * Returns True, envelope is degenerate (Width or Height are less than - * tolerance). Note: this returns False for Empty envelope. + * @param tolerance + * the resolution for degenerate classification + * + * @return {@code true} if envelope is degenerate (Width or Height are less + * than tolerance). Note: this returns {@code false} for Empty + * envelope. */ public boolean isDegenerate(double tolerance) { return !isEmpty() @@ -1035,8 +1084,11 @@ public boolean isPointOnBoundary(Point2D pt, double tolerance) { } /** - * Calculates minimum distance from this envelope to the other. - * Returns 0 for empty envelopes. + * @param other + * envelope for minimum distance calculation + * + * @return the minimum distance from this envelope to the other or 0 for + * empty envelopes */ public double distance(/* const */Envelope2D other) { @@ -1044,8 +1096,11 @@ public double distance(/* const */Envelope2D other) } /** - * Calculates minimum distance from this envelope to the point. - * Returns 0 for empty envelopes. + * @param pt2D + * the point for minimum distance calculation + * + * @return the minimum distance from this envelope to the given point or 0 + * for empty envelopes */ public double distance(Point2D pt2D) { @@ -1053,8 +1108,11 @@ public double distance(Point2D pt2D) } /** - * Calculates minimum squared distance from this envelope to the other. - * Returns 0 for empty envelopes. + * @param other + * envelope for squared distance calculation + * + * @return minimum squared distance from this envelope to the other or 0 + * for empty envelopes */ public double sqrDistance(Envelope2D other) { @@ -1083,7 +1141,12 @@ public double sqrDistance(Envelope2D other) /** * Calculates minimum squared distance from this envelope to the point. - * Returns 0 for empty envelopes. + * + * @param pt2D + * the point to calculate the minimum squared distance from the envelope + * + * @return the minimum squared distance from the input parameter or 0 for + * empty envelopes */ public double sqrDistance(Point2D pt2D) { diff --git a/src/main/java/com/esri/core/geometry/Envelope2DIntersectorImpl.java b/src/main/java/com/esri/core/geometry/Envelope2DIntersectorImpl.java index 98d7ad8c..3311c728 100644 --- a/src/main/java/com/esri/core/geometry/Envelope2DIntersectorImpl.java +++ b/src/main/java/com/esri/core/geometry/Envelope2DIntersectorImpl.java @@ -248,8 +248,10 @@ int getHandleB() { } /* - * Sets the tolerance used for the intersection tests.\param tolerance The - * tolerance used to determine intersection. + * Sets the tolerance used for the intersection tests. + * + * @param tolerance + * The tolerance used to determine intersection. */ void setTolerance(double tolerance) { m_tolerance = tolerance; diff --git a/src/main/java/com/esri/core/geometry/Geometry.java b/src/main/java/com/esri/core/geometry/Geometry.java index e5d08afa..6fd2b53c 100644 --- a/src/main/java/com/esri/core/geometry/Geometry.java +++ b/src/main/java/com/esri/core/geometry/Geometry.java @@ -108,7 +108,7 @@ static public enum Type { private int enumValue; /** - * Returns the integer representation of the enumeration value. + * @return the integer representation of the enumeration value. */ public int value() { return enumValue; @@ -143,7 +143,8 @@ public int value() { public abstract int getDimension(); /** - * Returns the VertexDescription of this geomtry. + + * @return the VertexDescription of this geometry. */ public VertexDescription getDescription() { return m_description; @@ -183,6 +184,12 @@ void mergeVertexDescription(VertexDescription src) { /** * A shortcut for getDescription().hasAttribute() + * + * @param semantics + * the {@link VertexDescription.Semantics} for the attribute + * + * @return {@code true} if geometry has the attribute matching the + * semantics of the attribute. */ public boolean hasAttribute(int semantics) { return getDescription().hasAttribute(semantics); @@ -191,7 +198,7 @@ public boolean hasAttribute(int semantics) { /** * Adds a new attribute to the Geometry. * - * @param semantics + * @param semantics for the attribute */ public void addAttribute(int semantics) { _touch(); @@ -207,6 +214,9 @@ public void addAttribute(int semantics) { * equivalent to setting the attribute to the default value for each vertex, * However, it is faster and the result Geometry has smaller memory * footprint and smaller size when persisted. + * + * @param semantics + * for the attribute */ public void dropAttribute(int semantics) { _touch(); @@ -226,7 +236,13 @@ public void dropAllAttributes() { } /** - * Returns the min and max attribute values at the ordinate of the Geometry + * @param semantics + * as defined in {@link VertexDescription.Semantics} + * + * @param ordinate + * value TODO + * + * @return the min and max attribute values at the ordinate of the Geometry */ public abstract Envelope1D queryInterval(int semantics, int ordinate); @@ -246,6 +262,9 @@ public void dropAllAttributes() { /** * Returns tight bbox of the Geometry in X, Y plane. + * + * @param env + * the envelope to update with the X and Y extents of the geometry */ public abstract void queryEnvelope2D(Envelope2D env); @@ -258,6 +277,10 @@ public void dropAllAttributes() { * Returns the conservative bbox of the Geometry in X, Y plane. This is a * faster method than QueryEnvelope2D. However, the bbox could be larger * than the tight box. + * + * @param env + * the envelope to update with the loose X and Y extents of the + * geometry */ public void queryLooseEnvelope2D(Envelope2D env) { queryEnvelope2D(env); @@ -276,7 +299,7 @@ void queryLooseEnvelope3D(Envelope3D env) { * IsEmpty returns TRUE when the Geometry object does not contain geometric * information beyond its original initialization state. * - * @return boolean Returns TRUE if this geometry is empty. + * @return {@code true} if this geometry is empty. */ public abstract boolean isEmpty(); @@ -289,8 +312,8 @@ void queryLooseEnvelope3D(Envelope3D env) { /** * Applies 2D affine transformation in XY plane. * - * @param transform - * The affine transformation to be applied to this geometry. + * @param transform + * The affine transformation to be applied to this geometry. */ public abstract void applyTransformation(Transformation2D transform); @@ -303,14 +326,17 @@ void queryLooseEnvelope3D(Envelope3D env) { abstract void applyTransformation(Transformation3D transform); /** - * Creates an instance of an empty geometry of the same type. + * @return a new instance of an empty geometry of the same type. */ public abstract Geometry createInstance(); /** * Copies this geometry to another geometry of the same type. The result * geometry is an exact copy. - * + * + * @param dst + * the destination geometry + * * @exception GeometryException * invalid_argument if the geometry is of different type. */ @@ -355,7 +381,7 @@ void addZ() { /** * Returns true if this Geometry has the Z attribute * - * @return true if this Geometry has the Z attribute + * @return {@code true} if this Geometry has the Z attribute */ public boolean hasZ() { return hasAttribute(VertexDescription.Semantics.Z); @@ -371,7 +397,7 @@ public void addM() { /** * Returns true if this Geometry has an M attribute * - * @return true if this Geometry has an M attribute + * @return {@code true} if this Geometry has an M attribute */ public boolean hasM() { return hasAttribute(VertexDescription.Semantics.M); @@ -387,7 +413,7 @@ public void addID() { /** * Returns true if this Geometry has an ID attribute * - * @return true if this Geometry has an ID attribute + * @return {@code true} if this Geometry has an ID attribute */ public boolean hasID() { return hasAttribute(VertexDescription.Semantics.ID); @@ -417,10 +443,11 @@ public static int getDimensionFromType(int type) { * Indicates if the integer value of the enumeration is a point type * (dimension 0). * - * @param type - * The integer value from geometry enumeration. You can use the - * method {@link Type#value()} to get at the integer value. - * @return TRUE if the geometry is a point. + * @param type + * The integer value from geometry enumeration. You can use the + * method {@link Type#value()} to get at the integer value. + * + * @return {@code true} if the geometry is a point. */ public static boolean isPoint(int type) { return (type & 0x20) != 0; @@ -430,10 +457,11 @@ public static boolean isPoint(int type) { * Indicates if the integer value of the enumeration is linear (dimension * 1). * - * @param type - * The integer value from geometry enumeration. You can use the - * method {@link Type#value()} to get at the integer value. - * @return TRUE if the geometry is a line. + * @param type + * The integer value from geometry enumeration. You can use the + * method {@link Type#value()} to get at the integer value. + * + * @return {@code true} if the geometry is a line. */ public static boolean isLinear(int type) { return (type & 0x40) != 0; @@ -443,10 +471,11 @@ public static boolean isLinear(int type) { * Indicates if the integer value of the enumeration is an area (dimension * 2). * - * @param type - * The integer value from geometry enumeration. You can use the - * method {@link Type#value()} to get at the integer value. - * @return TRUE if the geometry is a polygon. + * @param type + * The integer value from geometry enumeration. You can use the + * method {@link Type#value()} to get at the integer value. + * + * @return {@code true} if the geometry is a polygon. */ public static boolean isArea(int type) { return (type & 0x80) != 0; @@ -456,9 +485,10 @@ public static boolean isArea(int type) { * Indicates if the integer value of the enumeration is a segment. * * @param type - * The integer value from geometry enumeration. You can use the - * method {@link Type#value()} to get at the integer value. - * @return TRUE if the geometry is a segment. + * The integer value from geometry enumeration. You can use the + * method {@link Type#value()} to get at the integer value. + * + * @return {@code true} if the geometry is a segment. */ public static boolean isSegment(int type) { return (type & 0x100) != 0; @@ -468,10 +498,11 @@ public static boolean isSegment(int type) { * Indicates if the integer value of the enumeration is a multivertex (ie, * multipoint, line, or area). * - * @param type - * The integer value from geometry enumeration. You can use the - * method {@link Type#value()} to get at the integer value. - * @return TRUE if the geometry has multiple vertices. + * @param type + * The integer value from geometry enumeration. You can use the + * method {@link Type#value()} to get at the integer value. + * + * @return {@code true} if the geometry has multiple vertices. */ public static boolean isMultiVertex(int type) { return (type & 0x200) != 0; @@ -481,10 +512,11 @@ public static boolean isMultiVertex(int type) { * Indicates if the integer value of the enumeration is a multipath (ie, * line or area). * - * @param type - * The integer value from geometry enumeration. You can use the - * method {@link Type#value()} to get at the integer value. - * @return TRUE if the geometry is a multipath. + * @param type + * The integer value from geometry enumeration. You can use the + * method {@link Type#value()} to get at the integer value. + * + * @return {@code true} if the geometry is a multipath. */ public static boolean isMultiPath(int type) { return (type & 0x400) != 0; @@ -493,7 +525,7 @@ public static boolean isMultiPath(int type) { /** * Creates a copy of the geometry. * - * @return Returns a copy of this geometry. + * @return a copy of this geometry. */ public Geometry copy() { Geometry geom = createInstance(); @@ -502,11 +534,11 @@ public Geometry copy() { } /** - * Returns boundary of this geometry. - * * Polygon and Envelope boundary is a Polyline. For Polyline and Line, the * boundary is a Multi_point consisting of path endpoints. For Multi_point * and Point NULL is returned. + * + * @return the boundary of this geometry */ public abstract Geometry getBoundary(); @@ -514,7 +546,12 @@ public Geometry copy() { * Replaces NaNs in the attribute with the given value. * If the geometry is not empty, it adds the attribute if geometry does not have it yet, and replaces the values. * If the geometry is empty, it adds the attribute and does not set any values. - * + * + * @param semantics + * the {@link VertexDescription.Semantics} NaN replacement - TODO + * + * @param value + * the element value for replacement - TODO */ public abstract void replaceNaNs(int semantics, double value); @@ -586,11 +623,16 @@ public String toString() { } /** - *Returns count of geometry vertices: - *1 for Point, 4 for Envelope, get_point_count for MultiVertexGeometry types, - *2 for segment types - *Returns 0 if geometry is empty. - */ + * Returns count of geometry vertices: + * 1 for Point, 4 for Envelope, get_point_count for MultiVertexGeometry types, + * 2 for segment types + * Returns 0 if geometry is empty. + * + * @param geom + * input to perform the vertex count on + * + * @return count of geometry vertices + */ public static int vertex_count(Geometry geom) { Geometry.Type gt = geom.getType(); if (Geometry.isMultiVertex(gt.value())) diff --git a/src/main/java/com/esri/core/geometry/GeometryCursor.java b/src/main/java/com/esri/core/geometry/GeometryCursor.java index 3c2ef5d6..3ee75b24 100644 --- a/src/main/java/com/esri/core/geometry/GeometryCursor.java +++ b/src/main/java/com/esri/core/geometry/GeometryCursor.java @@ -27,25 +27,36 @@ *An abstract Geometry Cursor class. */ public abstract class GeometryCursor { - /** - *Moves the cursor to the next Geometry. Returns null when reached the end. - *The behavior of the cursor is undefined after the method returns null. - */ - public abstract Geometry next(); + + /** + * Moves the cursor to the next Geometry. Returns null when reached the end. + * The behavior of the cursor is undefined after the method returns null. + * + * @return the next geometry or null when the end is reached + */ + public abstract Geometry next(); + + /** + * An ID is associated with the current Geometry. The ID is passed along + * and is returned by some operators to preserve relationship between the + * input and output geometry classes. + * + * The ID is propagated across the operations when possible as the ID + * cannot always be preserved by some operations. + * + * @return the ID of the current geometry + */ + public abstract int getGeometryID(); /** - *Returns the ID of the current geometry. The ID is propagated across the operations (when possible). - * - *Returns an ID associated with the current Geometry. The ID is passed along and is returned by some operators to preserve relationship between the input and output geometry classes. - *It is not always possible to preserve an ID during an operation. - */ - public abstract int getGeometryID(); - /** - *Executes a unit of work on the cursor. - *@return Returns true, if there is a geometry ready to be pulled using next(). - * - *This method is to be used together with the tick() method on the ListeningGeometryCursor. - *Call tock() for each tick() on the ListeningGeometryCursor. - */ - public boolean tock() { return true; } + * Executes a unit of work on the cursor. + * + * This method is to be used together with the tick() method on the + * ListeningGeometryCursor. + * Call tock() for each tick() on the ListeningGeometryCursor. + * + * @return {@code true}, if there is a geometry ready to be pulled using + * next(). + */ + public boolean tock() { return true; } } diff --git a/src/main/java/com/esri/core/geometry/GeometryEngine.java b/src/main/java/com/esri/core/geometry/GeometryEngine.java index e027dd6c..fe62bc6f 100644 --- a/src/main/java/com/esri/core/geometry/GeometryEngine.java +++ b/src/main/java/com/esri/core/geometry/GeometryEngine.java @@ -43,16 +43,17 @@ public class GeometryEngine { private static OperatorFactoryLocal factory = OperatorFactoryLocal .getInstance(); - + /** * Imports the MapGeometry from its JSON representation. M and Z values are * not imported from JSON representation. * * See OperatorImportFromJson. * - * @param json - * The JSON representation of the geometry (with spatial - * reference). + * @param json + * The JSON representation of the geometry (with spatial + * reference). + * * @return The MapGeometry instance containing the imported geometry and its * spatial reference. */ @@ -67,13 +68,18 @@ public static MapGeometry jsonToGeometry(JsonParser json) { * * See OperatorImportFromJson. * - * @param json - * The JSON representation of the geometry (with spatial - * reference). + * @param json + * The JSON representation of the geometry (with spatial + * reference). + * * @return The MapGeometry instance containing the imported geometry and its * spatial reference. - * @throws IOException - * @throws JsonParseException + * + * @throws IOException + * if an I/O error occurs. + * + * @throws JsonParseException + * if a parse error occurs. */ public static MapGeometry jsonToGeometry(String json) throws JsonParseException, IOException { MapGeometry geom = OperatorImportFromJson.local().execute(Geometry.Type.Unknown, json); @@ -87,11 +93,14 @@ public static MapGeometry jsonToGeometry(String json) throws JsonParseException, * * @see GeometryEngine#geometryToJson(SpatialReference spatialiReference, * Geometry geometry) - * @param wkid - * The spatial reference Well Known ID to be used for the JSON - * representation. - * @param geometry - * The geometry to be exported to JSON. + * + * @param wkid + * The spatial reference Well Known ID to be used for the JSON + * representation. + * + * @param geometry + * The geometry to be exported to JSON. + * * @return The JSON representation of the specified Geometry. */ public static String geometryToJson(int wkid, Geometry geometry) { @@ -105,10 +114,12 @@ public static String geometryToJson(int wkid, Geometry geometry) { * * See OperatorExportToJson. * - * @param spatialReference - * The spatial reference of associated object. - * @param geometry - * The geometry. + * @param spatialReference + * The spatial reference of associated object. + * + * @param geometry + * The geometry. + * * @return The JSON representation of the specified geometry. */ public static String geometryToJson(SpatialReference spatialReference, @@ -134,10 +145,12 @@ public static String geometryToGeoJson(Geometry geometry) { * @see GeometryEngine#geometryToGeoJson(SpatialReference spatialReference, * Geometry geometry) * - * @param wkid - * The spatial reference Well Known ID to be used for the GeoJSON representation. - * @param geometry - * The geometry to be exported to GeoJSON. + * @param wkid + * The spatial reference Well Known ID to be used for the GeoJSON representation. + * + * @param geometry + * The geometry to be exported to GeoJSON. + * * @return The GeoJSON representation of the specified geometry. */ public static String geometryToGeoJson(int wkid, Geometry geometry) { @@ -150,10 +163,12 @@ public static String geometryToGeoJson(int wkid, Geometry geometry) { * *See OperatorImportFromGeoJson. * - * @param spatialReference - * The spatial reference of associated object. - * @param geometry - * The geometry. + * @param spatialReference + * The spatial reference of associated object. + * + * @param geometry + * The geometry + * * @return The GeoJSON representation of the specified geometry. */ public static String geometryToGeoJson(SpatialReference spatialReference, @@ -169,18 +184,21 @@ public static String geometryToGeoJson(SpatialReference spatialReference, * * See OperatorImportFromESRIShape. * - * @param esriShapeBuffer - * The buffer containing geometry in the ESRI shape file format. - * @param geometryType - * The required type of the Geometry to be imported. Use - * Geometry.Type.Unknown if the geometry type needs to be - * determined from the buffer content. + * @param esriShapeBuffer + * The buffer containing geometry in the ESRI shape file format. + * + * @param geometryType + * The required type of the Geometry to be imported. Use + * Geometry.Type.Unknown if the geometry type needs to be + * determined from the buffer content. + * * @return The geometry or null if the buffer contains null shape. + * * @throws GeometryException - * when the geometryType is not Geometry.Type.Unknown and the - * buffer contains geometry that cannot be converted to the - * given geometryType. or the buffer is corrupt. Another - * exception possible is IllegalArgumentsException. + * when the geometryType is not Geometry.Type.Unknown and the + * buffer contains geometry that cannot be converted to the + * given geometryType. or the buffer is corrupt. Another + * exception possible is IllegalArgumentsException. */ public static Geometry geometryFromEsriShape(byte[] esriShapeBuffer, Geometry.Type geometryType) { @@ -199,8 +217,9 @@ public static Geometry geometryFromEsriShape(byte[] esriShapeBuffer, * * See OperatorExportToESRIShape. * - * @param geometry - * The geometry to export. (null value is not allowed) + * @param geometry + * The geometry to export. (null value is not allowed) + * * @return Array containing the exported ESRI shape file. */ public static byte[] geometryToEsriShape(Geometry geometry) { @@ -216,12 +235,22 @@ public static byte[] geometryToEsriShape(Geometry geometry) { * * See OperatorImportFromWkt. * - * @param wkt The string containing the geometry in WKT format. - * @param importFlags Use the {@link WktImportFlags} interface. - * @param geometryType The required type of the Geometry to be imported. Use Geometry.Type.Unknown if the geometry type needs to be determined from the WKT context. + * @param wkt + * The string containing the geometry in WKT format. + * + * @param importFlags + * Use the {@link WktImportFlags} interface. + * + * @param geometryType + * The required type of the Geometry to be imported. Use Geometry.Type.Unknown if the geometry type needs to be determined from the WKT context. + * * @return The geometry. - * @throws GeometryException when the geometryType is not Geometry.Type.Unknown and the WKT contains a geometry that cannot be converted to the given geometryType. - * @throws IllegalArgument exception if an error is found while parsing the WKT string. + * + * @throws GeometryException + * when the geometryType is not Geometry.Type.Unknown and the WKT contains a geometry that cannot be converted to the given geometryType. + * + * @throws IllegalArgumentException + * exception if an error is found while parsing the WKT string. */ public static Geometry geometryFromWkt(String wkt, int importFlags, Geometry.Type geometryType) { @@ -235,12 +264,22 @@ public static Geometry geometryFromWkt(String wkt, int importFlags, * * See OperatorImportFromGeoJson. * - * @param geoJson The string containing the geometry in geoJson format. - * @param importFlags Use the {@link GeoJsonImportFlags} interface. - * @param geometryType The required type of the Geometry to be imported. Use Geometry.Type.Unknown if the geometry type needs to be determined from the geoJson context. + * @param geoJson + * The string containing the geometry in geoJson format. + * + * @param importFlags + * Use the {@link GeoJsonImportFlags} interface. + * + * @param geometryType + * The required type of the Geometry to be imported. Use Geometry.Type.Unknown if the geometry type needs to be determined from the geoJson context. + * * @return The geometry. - * @throws GeometryException when the geometryType is not Geometry.Type.Unknown and the geoJson contains a geometry that cannot be converted to the given geometryType. - * @throws IllegalArgument exception if an error is found while parsing the geoJson string. + * + * @throws GeometryException + * when the geometryType is not Geometry.Type.Unknown and the geoJson contains a geometry that cannot be converted to the given geometryType. + * + * @throws IllegalArgumentException + * exception if an error is found while parsing the geoJson string. */ public static MapGeometry geometryFromGeoJson(String geoJson, int importFlags, Geometry.Type geometryType) throws JSONException { @@ -254,9 +293,13 @@ public static MapGeometry geometryFromGeoJson(String geoJson, * * See OperatorExportToWkt. * - * @param geometry The geometry to export. (null value is not allowed) - * @param exportFlags Use the {@link WktExportFlags} interface. - * @return A String containing the exported geometry in WKT format. + * @param geometry + * The geometry to export. (null value is not allowed) + * + * @param exportFlags + * Use the {@link WktExportFlags} interface. + * + * @return a String containing the exported geometry in WKT format. */ public static String geometryToWkt(Geometry geometry, int exportFlags) { OperatorExportToWkt op = (OperatorExportToWkt) factory @@ -270,11 +313,13 @@ public static String geometryToWkt(Geometry geometry, int exportFlags) { * * See OperatorUnion. * - * @param geometries - * The geometries to union. - * @param spatialReference - * The spatial reference of the geometries. - * @return The geometry object representing the resultant union. + * @param geometries + * The geometries to union. + * + * @param spatialReference + * The spatial reference of the geometries. + * + * @return the geometry object representing the resultant union. */ public static Geometry union(Geometry[] geometries, SpatialReference spatialReference) { @@ -294,13 +339,16 @@ public static Geometry union(Geometry[] geometries, * * See OperatorDifference. * - * @param geometry1 - * The geometry being subtracted. - * @param substractor - * The geometry object to subtract from. - * @param spatialReference - * The spatial reference of the geometries. - * @return The geometry of the differences. + * @param geometry1 + * The geometry being subtracted. + * + * @param substractor + * The geometry object to subtract from. + * + * @param spatialReference + * The spatial reference of the geometries. + * + * @return the geometry of the differences. */ public static Geometry difference(Geometry geometry1, Geometry substractor, SpatialReference spatialReference) { @@ -316,13 +364,16 @@ public static Geometry difference(Geometry geometry1, Geometry substractor, * * See OperatorSymmetricDifference. * - * @param leftGeometry - * is one of the Geometry instances in the XOR operation. - * @param rightGeometry - * is one of the Geometry instances in the XOR operation. - * @param spatialReference - * The spatial reference of the geometries. - * @return Returns the result of the symmetric difference. + * @param leftGeometry + * is one of the Geometry instances in the XOR operation. + * + * @param rightGeometry + * is one of the Geometry instances in the XOR operation. + * + * @param spatialReference + * The spatial reference of the geometries. + * + * @return the result of the symmetric difference. */ public static Geometry symmetricDifference(Geometry leftGeometry, Geometry rightGeometry, SpatialReference spatialReference) { @@ -338,13 +389,16 @@ public static Geometry symmetricDifference(Geometry leftGeometry, * * See OperatorEquals. * - * @param geometry1 - * Geometry. - * @param geometry2 - * Geometry. - * @param spatialReference - * The spatial reference of the geometries. - * @return TRUE if both geometry objects are equal. + * @param geometry1 + * first geometry for equality comparison. + * + * @param geometry2 + * second geometry for equality comparison. + * + * @param spatialReference + * The spatial reference of the geometries. + * + * @return {@code true} if both geometry objects are equal. */ public static boolean equals(Geometry geometry1, Geometry geometry2, SpatialReference spatialReference) { @@ -356,8 +410,18 @@ public static boolean equals(Geometry geometry1, Geometry geometry2, } /** - * See OperatorDisjoint. - * + * See {@link OperatorDisjoint}. + * + * @param geometry1 + * the first for comparison + * + * @param geometry2 + * the second for comparison + * + * @param spatialReference + * of the supplied geometry + * + * @return {@code true} if the geometry1 is disjoint to geometry2. */ public static boolean disjoint(Geometry geometry1, Geometry geometry2, SpatialReference spatialReference) { @@ -374,10 +438,12 @@ public static boolean disjoint(Geometry geometry1, Geometry geometry2, * * See OperatorIntersection (also for dimension specific intersection). * - * @param inputGeometries - * An array of geometry objects. - * @param geometry - * The geometry object. + * @param inputGeometries + * An array of geometry objects. + * + * @param geometry + * The geometry object. + * * @return Any array of geometry objects showing the intersection. */ static Geometry[] intersect(Geometry[] inputGeometries, Geometry geometry, @@ -406,12 +472,15 @@ static Geometry[] intersect(Geometry[] inputGeometries, Geometry geometry, * * See OperatorIntersection. * - * @param geometry1 - * The first geometry. - * @param intersector - * The geometry to intersect the first geometry. - * @param spatialReference - * The spatial reference of the geometries. + * @param geometry1 + * The first geometry. + * + * @param intersector + * The geometry to intersect the first geometry. + * + * @param spatialReference + * The spatial reference of the geometries. + * * @return The geometry created through intersection. */ public static Geometry intersect(Geometry geometry1, Geometry intersector, @@ -428,15 +497,18 @@ public static Geometry intersect(Geometry geometry1, Geometry intersector, * * See OperatorWithin. * - * @param geometry1 - * The base geometry that is tested for within relationship to - * the other geometry. - * @param geometry2 - * The comparison geometry that is tested for the contains - * relationship to the other geometry. - * @param spatialReference - * The spatial reference of the geometries. - * @return TRUE if the first geometry is within the other geometry. + * @param geometry1 + * The base geometry that is tested for within relationship to + * the other geometry. + * + * @param geometry2 + * The comparison geometry that is tested for the contains + * relationship to the other geometry. + * + * @param spatialReference + * The spatial reference of the geometries. + * + * @return {@code true} if the first geometry is within the other geometry. */ public static boolean within(Geometry geometry1, Geometry geometry2, SpatialReference spatialReference) { @@ -452,15 +524,18 @@ public static boolean within(Geometry geometry1, Geometry geometry2, * * See OperatorContains. * - * @param geometry1 - * The geometry that is tested for the contains relationship to - * the other geometry.. - * @param geometry2 - * The geometry that is tested for within relationship to the + * @param geometry1 + * The geometry that is tested for the contains relationship to + * the other geometry. + * + * @param geometry2 + * The geometry that is tested for within relationship to the * other geometry. - * @param spatialReference - * The spatial reference of the geometries. - * @return TRUE if geometry1 contains geometry2. + * + * @param spatialReference + * The spatial reference of the geometries. + * + * @return {@code true} if geometry1 contains geometry2. */ public static boolean contains(Geometry geometry1, Geometry geometry2, SpatialReference spatialReference) { @@ -476,13 +551,16 @@ public static boolean contains(Geometry geometry1, Geometry geometry2, * * See OperatorCrosses. * - * @param geometry1 - * The geometry to cross. - * @param geometry2 - * The geometry being crossed. - * @param spatialReference - * The spatial reference of the geometries. - * @return TRUE if geometry1 crosses geometry2. + * @param geometry1 + * The geometry to cross. + * + * @param geometry2 + * The geometry being crossed. + * + * @param spatialReference + * The spatial reference of the geometries. + * + * @return {@code true} if geometry1 crosses geometry2. */ public static boolean crosses(Geometry geometry1, Geometry geometry2, SpatialReference spatialReference) { @@ -498,13 +576,16 @@ public static boolean crosses(Geometry geometry1, Geometry geometry2, * * See OperatorTouches. * - * @param geometry1 - * The geometry to touch. - * @param geometry2 - * The geometry to be touched. - * @param spatialReference - * The spatial reference of the geometries. - * @return TRUE if geometry1 touches geometry2. + * @param geometry1 + * The geometry to touch. + * + * @param geometry2 + * The geometry to be touched. + * + * @param spatialReference + * The spatial reference of the geometries. + * + * @return {@code true} if geometry1 touches geometry2. */ public static boolean touches(Geometry geometry1, Geometry geometry2, SpatialReference spatialReference) { @@ -518,15 +599,18 @@ public static boolean touches(Geometry geometry1, Geometry geometry2, /** * Indicates if one geometry overlaps another geometry. * - * See OperatorOverlaps. + * See {@link OperatorOverlaps}. * - * @param geometry1 - * The geometry to overlap. - * @param geometry2 - * The geometry to be overlapped. - * @param spatialReference - * The spatial reference of the geometries. - * @return TRUE if geometry1 overlaps geometry2. + * @param geometry1 + * The geometry to overlap. + * + * @param geometry2 + * The geometry to be overlapped. + * + * @param spatialReference + * The spatial reference of the geometries. + * + * @return {@code true} if geometry1 overlaps geometry2. */ public static boolean overlaps(Geometry geometry1, Geometry geometry2, SpatialReference spatialReference) { @@ -542,15 +626,20 @@ public static boolean overlaps(Geometry geometry1, Geometry geometry2, * * See OperatorRelate. * - * @param geometry1 - * The first geometry for the relation. - * @param geometry2 - * The second geometry for the relation. - * @param spatialReference - * The spatial reference of the geometries. - * @param relation - * The DE-9IM relation. - * @return TRUE if the given relation holds between geometry1 and geometry2. + * @param geometry1 + * The first geometry for the relation. + * + * @param geometry2 + * The second geometry for the relation. + * + * @param spatialReference + * The spatial reference of the geometries. + * + * @param relation + * The DE-9IM relation. + * + * @return {@code true} if the given relation holds between geometry1 and + * geometry2. */ public static boolean relate(Geometry geometry1, Geometry geometry2, SpatialReference spatialReference, String relation) { @@ -566,13 +655,16 @@ public static boolean relate(Geometry geometry1, Geometry geometry2, * * See OperatorDistance. * - * @param geometry1 - * Geometry. - * @param geometry2 - * Geometry. - * @param spatialReference - * The spatial reference of the geometries. This parameter is not - * used and can be null. + * @param geometry1 + * Geometry. + * + * @param geometry2 + * Geometry. + * + * @param spatialReference + * The spatial reference of the geometries. This parameter is not + * used and can be null. + * * @return The distance between the two geometries. */ public static double distance(Geometry geometry1, Geometry geometry2, @@ -588,12 +680,15 @@ public static double distance(Geometry geometry1, Geometry geometry2, * * See OperatorClip. * - * @param geometry - * The geometry to be clipped. - * @param envelope - * The envelope used to clip. - * @param spatialReference - * The spatial reference of the geometries. + * @param geometry + * The geometry to be clipped. + * + * @param envelope + * The envelope used to clip. + * + * @param spatialReference + * The spatial reference of the geometries. + * * @return The geometry created by clipping. */ public static Geometry clip(Geometry geometry, Envelope envelope, @@ -621,12 +716,15 @@ public static Geometry clip(Geometry geometry, Envelope envelope, * * See OperatorCut. * - * @param cuttee - * The geometry to be cut. - * @param cutter - * The polyline to cut the geometry. - * @param spatialReference - * The spatial reference of the geometries. + * @param cuttee + * The geometry to be cut. + * + * @param cutter + * The polyline to cut the geometry. + * + * @param spatialReference + * The spatial reference of the geometries. + * * @return An array of geometries created from cutting. */ public static Geometry[] cut(Geometry cuttee, Polyline cutter, @@ -647,7 +745,8 @@ public static Geometry[] cut(Geometry cuttee, Polyline cutter, } return cutsList.toArray(new Geometry[0]); - } + } + /** * Calculates a buffer polygon for each geometry at each of the * corresponding specified distances. It is assumed that all geometries have @@ -656,11 +755,21 @@ public static Geometry[] cut(Geometry cuttee, Polyline cutter, * * See OperatorBuffer. * - * @param geometries An array of geometries to be buffered. - * @param spatialReference The spatial reference of the geometries. - * @param distances The corresponding distances for the input geometries to be buffered. - * @param toUnionResults TRUE if all geometries buffered at a given distance are to be unioned into a single polygon. - * @return The buffer of the geometries. + * @param geometries + * An array of geometries to be buffered. + * + * @param spatialReference + * The spatial reference of the geometries. + * + * @param distances + * The corresponding distances for the input geometries to be + * buffered. + * + * @param toUnionResults + * TRUE if all geometries buffered at a given distance are to be + * unioned into a single polygon. + * + * @return the buffer of the geometries. */ public static Polygon[] buffer(Geometry[] geometries, SpatialReference spatialReference, double[] distances, @@ -693,17 +802,24 @@ public static Polygon[] buffer(Geometry[] geometries, return buffers; } } - + + /** * Calculates a buffer polygon of the geometry as specified by the * distance input. The buffer is implemented in the xy-plane. * * See OperatorBuffer * - * @param geometry Geometry to be buffered. - * @param spatialReference The spatial reference of the geometry. - * @param distance The specified distance for buffer. Same units as the spatial reference. - * @return The buffer polygon at the specified distances. + * @param geometry + * Geometry to be buffered. + * + * @param spatialReference + * The spatial reference of the geometry. + * + * @param distance + * The specified distance for buffer. Same units as the spatial reference. + * + * @return the buffer polygon at the specified distances. */ public static Polygon buffer(Geometry geometry, SpatialReference spatialReference, double distance) { @@ -719,22 +835,25 @@ public static Polygon buffer(Geometry geometry, /** * Calculates the convex hull geometry. * - * See OperatorConvexHull. - * - * @param geometry The input geometry. - * @return Returns the convex hull. - * - * For a Point - returns the same point. For an Envelope - - * returns the same envelope. For a MultiPoint - If the point - * count is one, returns the same multipoint. If the point count - * is two, returns a polyline of the points. Otherwise computes - * and returns the convex hull polygon. For a Segment - returns a - * polyline consisting of the segment. For a Polyline - If - * consists of only one segment, returns the same polyline. - * Otherwise computes and returns the convex hull polygon. For a - * Polygon - If more than one path, or if the path isn't already - * convex, computes and returns the convex hull polygon. - * Otherwise returns the same polygon. + * See {@link OperatorConvexHull}. + * + * For a Point - returns the same point. For an Envelope - + * returns the same envelope. For a MultiPoint - If the point + * count is one, returns the same multipoint. If the point count + * is two, returns a polyline of the points. Otherwise computes + * and returns the convex hull polygon. For a Segment - returns a + * polyline consisting of the segment. For a Polyline - If + * consists of only one segment, returns the same polyline. + * Otherwise computes and returns the convex hull polygon. For a + * Polygon - If more than one path, or if the path isn't already + * convex, computes and returns the convex hull polygon. + * Otherwise returns the same polygon. + * + * @param geometry + * The input geometry. + * + * @return the convex hull. + * */ public static Geometry convexHull(Geometry geometry) { OperatorConvexHull op = (OperatorConvexHull) factory @@ -747,14 +866,17 @@ public static Geometry convexHull(Geometry geometry) { * * See OperatorConvexHull * - * @param geometries - * The input geometry array. - * @param b_merge - * Put true if you want the convex hull of all the geometries in - * the array combined. Put false if you want the convex hull of - * each geometry in the array individually. - * @return Returns an array of convex hulls. If b_merge is true, the result - * will be a one element array consisting of the merged convex hull. + * @param geometries + * The input geometry array. + * + * @param b_merge + * Put true if you want the convex hull of all the geometries in + * the array combined. Put false if you want the convex hull of + * each geometry in the array individually. + * + * @return an array of convex hulls. If b_merge is true, the result + * will be a one element array consisting of the merged convex + * hull. */ public static Geometry[] convexHull(Geometry[] geometries, boolean b_merge) { OperatorConvexHull op = (OperatorConvexHull) factory @@ -781,13 +903,21 @@ public static Geometry[] convexHull(Geometry[] geometries, boolean b_merge) { * Finds the coordinate of the geometry which is closest to the specified * point. * - * See OperatorProximity2D. + * See {@link OperatorProximity2D}. * - * @param inputPoint - * The point to find the nearest coordinate in the geometry for. - * @param geometry - * The geometry to consider. - * @return Proximity2DResult containing the nearest coordinate. + * @param inputPoint + * The point to find the nearest coordinate in the geometry for. + * + * @param geometry + * The geometry to consider. + * + * @param bTestPolygonInterior + * When true and geometry is a polygon the function will test + * if the input_point is inside of the polygon. When false, + * the function will not check if the point is inside of the + * polygon but only determine proximity to the boundary. + * + * @return a Proximity2DResult containing the nearest coordinate. */ public static Proximity2DResult getNearestCoordinate(Geometry geometry, Point inputPoint, boolean bTestPolygonInterior) { @@ -805,11 +935,13 @@ public static Proximity2DResult getNearestCoordinate(Geometry geometry, * * See OperatorProximity2D. * - * @param inputPoint - * The point to find the nearest vertex of the geometry for. - * @param geometry - * The geometry to consider. - * @return Proximity2DResult containing the nearest vertex. + * @param inputPoint + * The point to find the nearest vertex of the geometry for. + * + * @param geometry + * The geometry to consider. + * + * @return a Proximity2DResult containing the nearest vertex. */ public static Proximity2DResult getNearestVertex(Geometry geometry, Point inputPoint) { @@ -826,15 +958,19 @@ public static Proximity2DResult getNearestVertex(Geometry geometry, * * See OperatorProximity2D. * - * @param inputPoint - * The point to start from. - * @param geometry - * The geometry to consider. - * @param searchRadius - * The search radius. - * @param maxVertexCountToReturn - * The maximum number number of vertices to return. - * @return Proximity2DResult containing the array of nearest vertices. + * @param inputPoint + * The point to start from. + * + * @param geometry + * The geometry to consider. + * + * @param searchRadius + * The search radius. + * + * @param maxVertexCountToReturn + * The maximum number number of vertices to return. + * + * @return a Proximity2DResult containing the array of nearest vertices. */ public static Proximity2DResult[] getNearestVertices(Geometry geometry, Point inputPoint, double searchRadius, int maxVertexCountToReturn) { @@ -852,11 +988,13 @@ public static Proximity2DResult[] getNearestVertices(Geometry geometry, * * See OperatorSimplify and See OperatorSimplifyOGC. * - * @param geometry - * The geometry to be simplified. - * @param spatialReference - * The spatial reference of the geometry to be simplified. - * @return The simplified geometry. + * @param geometry + * The geometry to be simplified. + * + * @param spatialReference + * The spatial reference of the geometry to be simplified. + * + * @return the simplified geometry. */ public static Geometry simplify(Geometry geometry, SpatialReference spatialReference) { @@ -871,11 +1009,13 @@ public static Geometry simplify(Geometry geometry, * * See OperatorSimplify. * - * @param geometry - * The geometry to be checked. - * @param spatialReference - * The spatial reference of the geometry. - * @return TRUE if the geometry is simple. + * @param geometry + * The geometry to be checked. + * + * @param spatialReference + * The spatial reference of the geometry. + * + * @return {@code true} if the geometry is simple. */ static boolean isSimple(Geometry geometry, SpatialReference spatialReference) { OperatorSimplify op = (OperatorSimplify) factory @@ -883,14 +1023,20 @@ static boolean isSimple(Geometry geometry, SpatialReference spatialReference) { boolean result = op.isSimpleAsFeature(geometry, spatialReference, null); return result; } - + + /** * A geodesic distance is the shortest distance between any two points on the earth's surface when the earth's * surface is approximated by a spheroid. The function returns the shortest distance between two points on the - * WGS84 spheroid. - * @param ptFrom The "from" point: long, lat in degrees. - * @param ptTo The "to" point: long, lat in degrees. - * @return The geodesic distance between two points in meters. + * WGS84 spheroid. + * + * @param ptFrom + * The "from" point: long, lat in degrees. + * + * @param ptTo + * The "to" point: long, lat in degrees. + * + * @return the geodesic distance between two points in meters. */ public static double geodesicDistanceOnWGS84(Point ptFrom, Point ptTo) { return SpatialReferenceImpl.geodesicDistanceOnWGS84Impl(ptFrom, ptTo); diff --git a/src/main/java/com/esri/core/geometry/IntervalTreeImpl.java b/src/main/java/com/esri/core/geometry/IntervalTreeImpl.java index acdc10d8..79f0076e 100644 --- a/src/main/java/com/esri/core/geometry/IntervalTreeImpl.java +++ b/src/main/java/com/esri/core/geometry/IntervalTreeImpl.java @@ -29,9 +29,13 @@ final class IntervalTreeImpl { static final class IntervalTreeIteratorImpl { /** * Resets the iterator to a starting state on the Interval_tree_impl - * using the input Envelope_1D interval as the query \param query The - * Envelope_1D interval used for the query. \param tolerance The - * tolerance used for the intersection tests. + * using the input Envelope_1D interval as the query + * + * @param query + * The Envelope_1D interval used for the query. + * + * @param tolerance + * The tolerance used for the intersection tests. */ void resetIterator(Envelope1D query, double tolerance) { m_query.vmin = query.vmin - tolerance; @@ -43,9 +47,16 @@ void resetIterator(Envelope1D query, double tolerance) { /** * Resets the iterator to a starting state on the Interval_tree_impl - * using the input Envelope_1D interval as the query \param query The - * Envelope_1D interval used for the query. \param tolerance The - * tolerance used for the intersection tests. + * using the input Envelope_1D interval as the query + * + * @param query_min + * The Envelope_1D interval used for the query. TODO verify + * + * @param query_max + * The Envelope_1D interval used for the query. TODO verify + * + * @param tolerance + * The tolerance used for the intersection tests. */ void resetIterator(double query_min, double query_max, double tolerance) { if (query_min > query_max) @@ -60,9 +71,13 @@ void resetIterator(double query_min, double query_max, double tolerance) { /** * Resets the iterator to a starting state on the Interval_tree_impl - * using the input double as the stabbing query \param query The double - * used for the query. \param tolerance The tolerance used for the - * intersection tests. + * using the input double as the stabbing query + * + * @param query + * The double used for the query. + * + * @param tolerance + * The tolerance used for the intersection tests. */ void resetIterator(double query, double tolerance) { m_query.vmin = query - tolerance; @@ -478,8 +493,10 @@ void endConstruction() { /** * Inserts the interval from the given index into the Interval_tree_impl. - * This operation can only be performed in the offline dynamic case. \param - * index The index containing the interval to be inserted. + * This operation can only be performed in the offline dynamic case. + * + * @param index + * The index containing the interval to be inserted. */ void insert(int index) { if (!m_b_offline_dynamic || !m_b_construction_ended) @@ -521,8 +538,11 @@ void insert(int index) { } /** - * Deletes the interval from the Interval_tree_impl. \param index The index - * containing the interval to be deleted from the Interval_tree_impl. + * Deletes the interval from the Interval_tree_impl. + * + * @param index + * the index containing the interval to be deleted from the + * Interval_tree_impl. */ void remove(int index) { if (!m_b_offline_dynamic || !m_b_construction_ended) @@ -637,9 +657,13 @@ int size() { * Gets an iterator on the Interval_tree_impl using the input Envelope_1D * interval as the query. To reuse the existing iterator on the same * Interval_tree_impl but with a new query, use the reset_iterator function - * on the Interval_tree_iterator_impl. \param query The Envelope_1D interval - * used for the query. \param tolerance The tolerance used for the - * intersection tests. + * on the Interval_tree_iterator_impl. + * + * @param query + * The Envelope_1D interval used for the query. + * + * @param tolerance + * The tolerance used for the intersection tests. */ IntervalTreeIteratorImpl getIterator(Envelope1D query, double tolerance) { return new IntervalTreeImpl.IntervalTreeIteratorImpl(this, query, @@ -650,9 +674,13 @@ IntervalTreeIteratorImpl getIterator(Envelope1D query, double tolerance) { * Gets an iterator on the Interval_tree_impl using the input double as the * stabbing query. To reuse the existing iterator on the same * Interval_tree_impl but with a new query, use the reset_iterator function - * on the Interval_tree_iterator_impl. \param query The double used for the - * stabbing query. \param tolerance The tolerance used for the intersection - * tests. + * on the Interval_tree_iterator_impl. + * + * @param query + * The double used for the stabbing query. + * + * @param tolerance + * The tolerance used for the intersection tests. */ IntervalTreeIteratorImpl getIterator(double query, double tolerance) { return new IntervalTreeImpl.IntervalTreeIteratorImpl(this, query, diff --git a/src/main/java/com/esri/core/geometry/JsonCursor.java b/src/main/java/com/esri/core/geometry/JsonCursor.java index 0af0024f..1af6f146 100644 --- a/src/main/java/com/esri/core/geometry/JsonCursor.java +++ b/src/main/java/com/esri/core/geometry/JsonCursor.java @@ -28,19 +28,22 @@ */ public abstract class JsonCursor { - /** - * Moves the cursor to the next string. Returns null when reached the end. - */ - public abstract String next(); - - /** - * Returns the ID of the current geometry. The ID is propagated across the - * operations (when possible). - * - * Returns an ID associated with the current Geometry. The ID is passed - * along and is returned by some operators to preserve relationship between - * the input and output geometry classes. It is not always possible to - * preserve an ID during an operation. - */ - public abstract int getID(); + /** + * Moves the cursor to the next string. + * + * @return the next value or null when the end is reached. + */ + public abstract String next(); + + /** + * Returns an ID associated with the current Geometry. The ID is + * propagated across the operations (when possible). + * The ID is passed along and is returned by some operators to preserve + * relationship between the input and output geometry classes. It is not + * always possible to preserve an ID during an operation. + * + * @return the ID of the current geometry. The ID is propagated across the + * operations (when possible). + */ + public abstract int getID(); } diff --git a/src/main/java/com/esri/core/geometry/MapGeometry.java b/src/main/java/com/esri/core/geometry/MapGeometry.java index d7161d52..0259250e 100644 --- a/src/main/java/com/esri/core/geometry/MapGeometry.java +++ b/src/main/java/com/esri/core/geometry/MapGeometry.java @@ -53,7 +53,7 @@ public MapGeometry(Geometry g, SpatialReference _sr) { } /** - * Gets the only geometry without the spatial reference from the + * @return the only geometry without the spatial reference from the * MapGeometry. */ public Geometry getGeometry() { @@ -82,7 +82,7 @@ public void setSpatialReference(SpatialReference sr) { } /** - * Gets the spatial reference for this MapGeometry. + * @return the spatial reference for this MapGeometry. */ public SpatialReference getSpatialReference() { return sr; diff --git a/src/main/java/com/esri/core/geometry/MathUtils.java b/src/main/java/com/esri/core/geometry/MathUtils.java index 208fe4ba..c9394d58 100644 --- a/src/main/java/com/esri/core/geometry/MathUtils.java +++ b/src/main/java/com/esri/core/geometry/MathUtils.java @@ -36,8 +36,10 @@ static final class KahanSummator { // startValue) /** - * initialize to the given start value. \param startValue_ The value to - * be added to the accumulated sum. + * initialize to the given start value. + * + * @param startValue_ + * The value to be added to the accumulated sum. */ KahanSummator(double startValue_) { startValue = startValue_; diff --git a/src/main/java/com/esri/core/geometry/MultiPath.java b/src/main/java/com/esri/core/geometry/MultiPath.java index 8e778725..66e9a0f2 100644 --- a/src/main/java/com/esri/core/geometry/MultiPath.java +++ b/src/main/java/com/esri/core/geometry/MultiPath.java @@ -209,14 +209,14 @@ public void queryCoordinates(Point[] dst) { } /** - * Returns TRUE if the multipath contains non-linear segments. + * @return {@code true} if the multipath contains non-linear segments. */ boolean hasNonLinearSegments() { return m_impl.hasNonLinearSegments(); } /** - * Returns total segment count in the MultiPath. + * @return total segment count in the MultiPath. */ public int getSegmentCount() { return m_impl.getSegmentCount(); @@ -225,8 +225,9 @@ public int getSegmentCount() { /** * Returns the segment count in the given multipath path. * - * @param pathIndex - * The path to determine the segment. + * @param pathIndex + * The path to determine the segment. + * * @return The segment of the multipath. */ public int getSegmentCount(int pathIndex) { @@ -239,11 +240,12 @@ public int getSegmentCount(int pathIndex) { /** * Appends all paths from another multipath. * - * @param src - * The multipath to append to this multipath. - * @param bReversePaths - * TRUE if the multipath is added should be added with its paths - * reversed. + * @param src + * The multipath to append to this multipath. + * + * @param bReversePaths + * {@code true} if the multipath is added should be added with its + * paths reversed. */ public void add(MultiPath src, boolean bReversePaths) { m_impl.add((MultiPathImpl) src._getImpl(), bReversePaths); @@ -252,12 +254,14 @@ public void add(MultiPath src, boolean bReversePaths) { /** * Copies a path from another multipath. * - * @param src - * The multipath to copy from. - * @param srcPathIndex - * The index of the path in the the source MultiPath. - * @param bForward - * When FALSE, the points are inserted in reverse order. + * @param src + * The multipath to copy from. + * + * @param srcPathIndex + * The index of the path in the the source MultiPath. + * + * @param bForward + * When FALSE, the points are inserted in reverse order. */ public void addPath(MultiPath src, int srcPathIndex, boolean bForward) { m_impl.addPath((MultiPathImpl) src._getImpl(), srcPathIndex, bForward); @@ -266,12 +270,14 @@ public void addPath(MultiPath src, int srcPathIndex, boolean bForward) { /** * Adds a new path to this multipath. * - * @param points - * The array of points to add to this multipath. - * @param count - * The number of points added to the mulitpath. - * @param bForward - * When FALSE, the points are inserted in reverse order. + * @param points + * The array of points to add to this multipath. + * + * @param count + * The number of points added to the mulitpath. + * + * @param bForward + * When FALSE, the points are inserted in reverse order. */ void addPath(Point2D[] points, int count, boolean bForward) { m_impl.addPath(points, count, bForward); @@ -280,10 +286,11 @@ void addPath(Point2D[] points, int count, boolean bForward) { /** * Adds a new segment to this multipath. * - * @param segment - * The segment to be added to this mulitpath. - * @param bStartNewPath - * TRUE if a new path will be added. + * @param segment + * The segment to be added to this mulitpath. + * + * @param bStartNewPath + * TRUE if a new path will be added. */ public void addSegment(Segment segment, boolean bStartNewPath) { m_impl.addSegment(segment, bStartNewPath); @@ -299,8 +306,8 @@ public void reverseAllPaths() { /** * Reverses the order of vertices in the path. * - * @param pathIndex - * The start index of the path to reverse the order. + * @param pathIndex + * The start index of the path to reverse the order. */ public void reversePath(int pathIndex) { m_impl.reversePath(pathIndex); @@ -309,8 +316,8 @@ public void reversePath(int pathIndex) { /** * Removes the path at the given index. * - * @param pathIndex - * The start index to remove the path. + * @param pathIndex + * The start index to remove the path. */ public void removePath(int pathIndex) { m_impl.removePath(pathIndex); @@ -319,15 +326,18 @@ public void removePath(int pathIndex) { /** * Inserts a path from another multipath. * - * @param pathIndex - * The start index of the multipath to insert. - * @param src - * The multipath to insert into this multipath. Can be the same - * as the multipath being modified. - * @param srcPathIndex - * The start index to insert the path into the multipath. - * @param bForward - * When FALSE, the points are inserted in reverse order. + * @param pathIndex + * The start index of the multipath to insert. + * + * @param src + * The multipath to insert into this multipath. Can be the same + * as the multipath being modified. + * + * @param srcPathIndex + * The start index to insert the path into the multipath. + * + * @param bForward + * When FALSE, the points are inserted in reverse order. */ public void insertPath(int pathIndex, MultiPath src, int srcPathIndex, boolean bForward) { @@ -338,16 +348,20 @@ public void insertPath(int pathIndex, MultiPath src, int srcPathIndex, /** * Inserts a path from an array of 2D Points. * - * @param pathIndex - * The path index of the multipath to place the new path. - * @param points - * The array of points defining the new path. - * @param pointsOffset - * The offset into the array to start reading. - * @param count - * The number of points to insert into the new path. - * @param bForward - * When FALSE, the points are inserted in reverse order. + * @param pathIndex + * The path index of the multipath to place the new path. + * + * @param points + * The array of points defining the new path. + * + * @param pointsOffset + * The offset into the array to start reading. + * + * @param count + * The number of points to insert into the new path. + * + * @param bForward + * When FALSE, the points are inserted in reverse order. */ void insertPath(int pathIndex, Point2D[] points, int pointsOffset, int count, boolean bForward) { @@ -359,24 +373,30 @@ void insertPath(int pathIndex, Point2D[] points, int pointsOffset, * vertices are connected by linear segments with each other and with the * existing vertices. * - * @param pathIndex - * The path index in this multipath to insert points to. Must - * correspond to an existing path. - * @param beforePointIndex - * The point index before all other vertices to insert in the - * given path of this multipath. This value must be between 0 and - * GetPathSize(pathIndex), or -1 to insert points at the end of - * the given path. - * @param src - * The source multipath. - * @param srcPathIndex - * The source path index to copy points from. - * @param srcPointIndexFrom - * The start point in the source path to start copying from. - * @param srcPointCount - * The count of points to add. - * @param bForward - * When FALSE, the points are inserted in reverse order. + * @param pathIndex + * The path index in this multipath to insert points to. Must + * correspond to an existing path. + * + * @param beforePointIndex + * The point index before all other vertices to insert in the + * given path of this multipath. This value must be between 0 and + * GetPathSize(pathIndex), or -1 to insert points at the end of + * the given path. + * + * @param src + * The source multipath. + * + * @param srcPathIndex + * The source path index to copy points from. + * + * @param srcPointIndexFrom + * The start point in the source path to start copying from. + * + * @param srcPointCount + * The count of points to add. + * + * @param bForward + * When FALSE, the points are inserted in reverse order. */ public void insertPoints(int pathIndex, int beforePointIndex, MultiPath src, int srcPathIndex, int srcPointIndexFrom, @@ -389,22 +409,27 @@ public void insertPoints(int pathIndex, int beforePointIndex, /** * Inserts a part of a path from the given array. * - * @param pathIndex - * The path index in this class to insert points to. Must - * correspond to an existing path. - * @param beforePointIndex - * The point index in the given path of this MultiPath before - * which the vertices need to be inserted. This value must be - * between 0 and GetPathSize(pathIndex), or -1 to insert points - * at the end of the given path. - * @param src - * The source array - * @param srcPointIndexFrom - * The start point in the source array to start copying from. - * @param srcPointCount - * The count of points to add. - * @param bForward - * When FALSE, the points are inserted in reverse order. + * @param pathIndex + * The path index in this class to insert points to. Must + * correspond to an existing path. + * + * @param beforePointIndex + * The point index in the given path of this MultiPath before + * which the vertices need to be inserted. This value must be + * between 0 and GetPathSize(pathIndex), or -1 to insert points + * at the end of the given path. + * + * @param src + * The source array + * + * @param srcPointIndexFrom + * The start point in the source array to start copying from. + * + * @param srcPointCount + * The count of points to add. + * + * @param bForward + * When FALSE, the points are inserted in reverse order. */ void insertPoints(int pathIndex, int beforePointIndex, Point2D[] src, int srcPointIndexFrom, int srcPointCount, boolean bForward) { @@ -415,15 +440,17 @@ void insertPoints(int pathIndex, int beforePointIndex, Point2D[] src, /** * Inserts a point. * - * @param pathIndex - * The path index in this class to insert the point to. Must - * correspond to an existing path. - * @param beforePointIndex - * The point index in the given path of this multipath. This - * value must be between 0 and GetPathSize(pathIndex), or -1 to - * insert the point at the end of the given path. - * @param pt - * The point to be inserted. + * @param pathIndex + * The path index in this class to insert the point to. Must + * correspond to an existing path. + * + * @param beforePointIndex + * The point index in the given path of this multipath. This + * value must be between 0 and GetPathSize(pathIndex), or -1 to + * insert the point at the end of the given path. + * + * @param pt + * The point to be inserted. */ void insertPoint(int pathIndex, int beforePointIndex, Point2D pt) { m_impl.insertPoint(pathIndex, beforePointIndex, pt); @@ -432,15 +459,17 @@ void insertPoint(int pathIndex, int beforePointIndex, Point2D pt) { /** * Inserts a point. * - * @param pathIndex - * The path index in this class to insert the point to. Must - * correspond to an existing path. - * @param beforePointIndex - * The point index in the given path of this multipath. This - * value must be between 0 and GetPathSize(pathIndex), or -1 to - * insert the point at the end of the given path. - * @param pt - * The point to be inserted. + * @param pathIndex + * The path index in this class to insert the point to. Must + * correspond to an existing path. + * + * @param beforePointIndex + * The point index in the given path of this multipath. This + * value must be between 0 and GetPathSize(pathIndex), or -1 to + * insert the point at the end of the given path. + * + * @param pt + * The point to be inserted. */ public void insertPoint(int pathIndex, int beforePointIndex, Point pt) { m_impl.insertPoint(pathIndex, beforePointIndex, pt); @@ -449,10 +478,11 @@ public void insertPoint(int pathIndex, int beforePointIndex, Point pt) { /** * Removes a point at a given index. * - * @param pathIndex - * The path from whom to remove the point. - * @param pointIndex - * The index of the point to be removed. + * @param pathIndex + * The path from whom to remove the point. + * + * @param pointIndex + * The index of the point to be removed. */ public void removePoint(int pathIndex, int pointIndex) { m_impl.removePoint(pathIndex, pointIndex); @@ -470,8 +500,9 @@ public int getPathCount() { /** * Returns the number of vertices in a path. * - * @param pathIndex - * The index of the path to return the number of vertices from. + * @param pathIndex + * The index of the path to return the number of vertices from. + * * @return The number of vertices in a path. */ public int getPathSize(int pathIndex) { @@ -481,8 +512,9 @@ public int getPathSize(int pathIndex) { /** * Returns the start index of the path. * - * @param pathIndex - * The index of the path to return the start index from. + * @param pathIndex + * The index of the path to return the start index from. + * * @return The start index of the path. * */ @@ -493,8 +525,9 @@ public int getPathStart(int pathIndex) { /** * Returns the index immediately following the last index of the path. * - * @param pathIndex - * The index of the path to return the end index from. + * @param pathIndex + * The index of the path to return the end index from. + * * @return Integer index after last index of path */ public int getPathEnd(int pathIndex) { @@ -504,8 +537,9 @@ public int getPathEnd(int pathIndex) { /** * Returns the path index from the point index. This is O(log N) operation. * - * @param pointIndex - * The index of the point. + * @param pointIndex + * The index of the point. + * * @return The index of the path. */ public int getPathIndexFromPointIndex(int pointIndex) { @@ -515,10 +549,11 @@ public int getPathIndexFromPointIndex(int pointIndex) { /** * Starts a new path at given coordinates. * - * @param x - * The X coordinate of the start point. - * @param y - * The Y coordinate of the start point. + * @param x + * The X coordinate of the start point. + * + * @param y + * The Y coordinate of the start point. */ public void startPath(double x, double y) { m_impl.startPath(x, y); @@ -535,8 +570,8 @@ void startPath(Point3D point) { /** * Starts a new path at a point. * - * @param point - * The point to start the path from. + * @param point + * The point to start the path from. */ public void startPath(Point point) { m_impl.startPath(point); @@ -545,10 +580,11 @@ public void startPath(Point point) { /** * Adds a line segment from the last point to the given end coordinates. * - * @param x - * The X coordinate to the end point. - * @param y - * The Y coordinate to the end point. + * @param x + * The X coordinate to the end point. + * + * @param y + * The Y coordinate to the end point. */ public void lineTo(double x, double y) { m_impl.lineTo(x, y); @@ -565,9 +601,9 @@ void lineTo(Point3D endPoint) { /** * Adds a Line Segment to the given end point. * - * @param endPoint - * The end point to which the newly added line segment should - * point. + * @param endPoint + * The end point to which the newly added line segment should + * point. */ public void lineTo(Point endPoint) { m_impl.lineTo(endPoint); @@ -626,9 +662,10 @@ public void closeAllPaths() { * path. The first point is not duplicated to close the path. Polygons * always have all paths closed. * - * @param pathIndex - * The index of the path to check to be closed. - * @return TRUE if the given path is closed (represents a Ring). + * @param pathIndex + * The index of the path to check to be closed. + * + * @return {@code true} if the given path is closed (represents a Ring). */ public boolean isClosedPath(int pathIndex) { return m_impl.isClosedPath(pathIndex); @@ -648,10 +685,11 @@ boolean hasNonLinearSegments(int pathIndex) { /** * Adds a rectangular closed Path to the MultiPathImpl. * - * @param envSrc - * is the source rectangle. - * @param bReverse - * Creates reversed path. + * @param envSrc + * is the source rectangle. + * + * @param bReverse + * Creates reversed path. */ public void addEnvelope(Envelope2D envSrc, boolean bReverse) { m_impl.addEnvelope(envSrc, bReverse); @@ -660,10 +698,11 @@ public void addEnvelope(Envelope2D envSrc, boolean bReverse) { /** * Adds a rectangular closed path to this multipath. * - * @param envSrc - * Is the envelope to add to this mulitpath. - * @param bReverse - * Adds the path reversed (counter-clockwise). + * @param envSrc + * Is the envelope to add to this mulitpath. + * + * @param bReverse + * Adds the path reversed (counter-clockwise). */ public void addEnvelope(Envelope envSrc, boolean bReverse) { m_impl.addEnvelope(envSrc, bReverse); @@ -686,8 +725,9 @@ public SegmentIterator querySegmentIterator() { * at the vertex. Calling PreviousSegment () will return the segment that * starts at the previous vertex. * - * @param startVertexIndex - * The start index of the SegementIterator. + * @param startVertexIndex + * The start index of the SegementIterator. + * * @return The SegmentIterator for this mulitpath at the specified vertex. */ public SegmentIterator querySegmentIteratorAtVertex(int startVertexIndex) { diff --git a/src/main/java/com/esri/core/geometry/MultiVertexGeometry.java b/src/main/java/com/esri/core/geometry/MultiVertexGeometry.java index 668d6b33..fffe2f62 100644 --- a/src/main/java/com/esri/core/geometry/MultiVertexGeometry.java +++ b/src/main/java/com/esri/core/geometry/MultiVertexGeometry.java @@ -41,17 +41,26 @@ protected void _assignVertexDescriptionImpl(VertexDescription newDescription) { } /** - * Returns the total vertex count in this Geometry. + * @return the total vertex count in this Geometry. */ public abstract int getPointCount(); /** - * Returns given vertex of the Geometry. + * @param index + * the position of the vertex for retrieval + * + * @return given vertex of the Geometry. */ public abstract Point getPoint(int index);// Java only /** * Returns given vertex of the Geometry by value. + * + * @param index + * the position of the vertex for retrieval + * + * @param ptOut + * the Point instance to apply the vertex coordinates */ public void getPoint(int index, Point ptOut) { getPointByVal(index, ptOut); @@ -60,22 +69,26 @@ public void getPoint(int index, Point ptOut) { /** * Sets the vertex at given index of the Geometry. * - * @param index - * The index of the vertex being changed. - * @param pointSrc - * The Point instance to set given vertex attributes from. The - * pointSrc can not be empty.
- * The method throws if the pointSrc is not of the Point type.
- * The attributes, that are present in the pointSrc and missing - * in this Geometry, will be added to the Geometry.
- * The vertex attributes missing in the pointSrc but present in - * the Geometry will be set to the default values (see - * VertexDescription::GetDefaultValue). + * @param index + * The index of the vertex being changed. + * + * @param pointSrc + * The Point instance to set given vertex attributes from. The + * pointSrc can not be empty.
+ * The method throws if the pointSrc is not of the Point type.
+ * The attributes, that are present in the pointSrc and missing + * in this Geometry, will be added to the Geometry.
+ * The vertex attributes missing in the pointSrc but present in + * the Geometry will be set to the default values (see + * VertexDescription::GetDefaultValue). */ public abstract void setPoint(int index, Point pointSrc);// Java only /** - * Returns XY coordinates of the given vertex of the Geometry. + * @param index + * the specified vertex position + * + * @return XY coordinates of the given vertex of the Geometry. */ public abstract Point2D getXY(int index); @@ -84,12 +97,23 @@ public void getPoint(int index, Point ptOut) { /** * Sets XY coordinates of the given vertex of the Geometry. All other * attributes are unchanged. + * + * @param index + * the specified vertex position + * + * @param pt + * the coordinates for the given index position */ public abstract void setXY(int index, Point2D pt); /** * Returns XYZ coordinates of the given vertex of the Geometry. If the * Geometry has no Z's, the default value for Z is returned (0). + * + * @param index + * of the required vertex + * + * @return XYZ coordinates of the given vertex of the Geometry */ abstract Point3D getXYZ(int index); @@ -97,11 +121,17 @@ public void getPoint(int index, Point ptOut) { * Sets XYZ coordinates of the given vertex of the Geometry. If Z attribute * is not present in this Geometry, it is added. All other attributes are * unchanged. + * + * @param index + * the specified vertex position + * + * @param pt + * the coordinates for the given index position */ abstract void setXYZ(int index, Point3D pt); /** - * Returns XY coordinates as an array. + * @return XY coordinates as an array. */ public Point2D[] getCoordinates2D() { Point2D[] arr = new Point2D[getPointCount()]; @@ -110,7 +140,7 @@ public Point2D[] getCoordinates2D() { } /** - * Returns XYZ coordinates as an array. + * @return XYZ coordinates as an array. */ Point3D[] getCoordinates3D() { Point3D[] arr = new Point3D[getPointCount()]; @@ -123,72 +153,104 @@ Point3D[] getCoordinates3D() { /** * Queries XY coordinates as an array. The array must be larg enough (See * GetPointCount()). + * + * @param dst + * array to contain XY coordinates for this geometry */ public abstract void queryCoordinates(Point2D[] dst); /** * Queries XYZ coordinates as an array. The array must be larg enough (See * GetPointCount()). + * + * @param dst + * array to contain XYZ coordinates for this geometry */ abstract void queryCoordinates(Point3D[] dst); /** - * Returns value of the given vertex attribute as double. + * @param semantics + * The attribute semantics. + * + * @param index + * is the vertex index in the Geometry. + * + * @param ordinate + * is the ordinate of a vertex attribute (for example, y has + * ordinate of 1, because it is second ordinate of POSITION) * - * @param semantics - * The atribute semantics. - * @param index - * is the vertex index in the Geometry. - * @param ordinate - * is the ordinate of a vertex attribute (for example, y has - * ordinate of 1, because it is second ordinate of POSITION) - * - * If attribute is not present, the default value is returned. - * See VertexDescription::GetDefaultValue() method. + * If attribute is not present, the default value is returned. + * See VertexDescription::GetDefaultValue() method. + * + * @return + * the value of the given vertex attribute as double. + * */ abstract double getAttributeAsDbl(int semantics, int index, int ordinate); /** - * Returns value of the given vertex attribute as int. - * - * @param semantics - * The atribute semantics. - * @param index - * is the vertex index in the Geometry. - * @param ordinate - * is the ordinate of a vertex attribute (for example, y has - * ordinate of 1, because it is second ordinate of POSITION) + * @param semantics + * The attribute semantics. + * + * @param index + * is the vertex index in the Geometry. + * + * @param ordinate + * is the ordinate of a vertex attribute (for example, y has + * ordinate of 1, because it is second ordinate of POSITION) * - * If attribute is not present, the default value is returned. - * See VertexDescription::GetDefaultValue() method. Avoid using - * this method on non-integer atributes. + * If attribute is not present, the default value is returned. + * See VertexDescription::GetDefaultValue() method. Avoid using + * this method on non-integer attributes. + * + * @return + * the value of the given vertex attribute as int. */ abstract int getAttributeAsInt(int semantics, int index, int ordinate); /** - * Sets the value of given attribute at given posisiotnsis. + * Sets the value of given attribute at given position. * - * @param semantics - * The atribute semantics. - * @param index - * is the vertex index in the Geometry. - * @param ordinate - * is the ordinate of a vertex attribute (for example, y has - * ordinate of 1, because it is seond ordinate of POSITION) - * @param value - * is the value to set. as well as the number of components of - * the attribute. + * @param semantics + * The attribute semantics. + * + * @param index + * is the vertex index in the Geometry. + * + * @param ordinate + * is the ordinate of a vertex attribute (for example, y has + * ordinate of 1, because it is seond ordinate of POSITION) + * + * @param value + * is the value to set. as well as the number of components of + * the attribute. * - * If the attribute is not present in this Geometry, it is added. + * If the attribute is not present in this Geometry, it is added. */ abstract void setAttribute(int semantics, int index, int ordinate, double value); /** - * Same as above, but works with ints. Avoid using this method on - * non-integer atributes because some double attributes may have NaN default - * values (e.g. Ms) + * Same as {@link MultiVertexGeometry#setAttribute(int, int, int, double)}, + * but works with ints. Avoid using this method on non-integer attributes + * because some double attributes may have NaN default values (e.g. Ms) + * + * @param semantics + * The attribute semantics. + * + * @param index + * is the vertex index in the Geometry. + * + * @param ordinate + * is the ordinate of a vertex attribute (for example, y has + * ordinate of 1, because it is seond ordinate of POSITION) + * + * @param value + * is the value to set. as well as the number of components of + * the attribute. + * + * If the attribute is not present in this Geometry, it is added. */ abstract void setAttribute(int semantics, int index, int ordinate, int value); @@ -196,23 +258,30 @@ abstract void setAttribute(int semantics, int index, int ordinate, /** * Returns given vertex of the Geometry. The outPoint will have same * VertexDescription as this Geometry. + * + * @param index + * the required vertex index in the Geometry. + * + * @param outPoint + * the Point to apply values for the specified index */ abstract void getPointByVal(int index, Point outPoint); /** * Sets the vertex at given index of the Geometry. * - * @param index - * The index of the vertex being changed. - * @param pointSrc - * The Point instance to set given vertex attributes from. The - * pointSrc can not be empty.
- * The method throws if the pointSrc is not of the Point type.
- * The attributes, that are present in the pointSrc and missing - * in this Geometry, will be added to the Geometry.
- * The vertex attributes missing in the pointSrc but present in - * the Geometry will be set to the default values (see - * VertexDescription::GetDefaultValue). + * @param index + * The index of the vertex being changed. + * + * @param pointSrc + * The Point instance to set given vertex attributes from. The + * pointSrc can not be empty.
+ * The method throws if the pointSrc is not of the Point type.
+ * The attributes, that are present in the pointSrc and missing + * in this Geometry, will be added to the Geometry.
+ * The vertex attributes missing in the pointSrc but present in + * the Geometry will be set to the default values (see + * VertexDescription::GetDefaultValue). */ abstract void setPointByVal(int index, Point pointSrc); diff --git a/src/main/java/com/esri/core/geometry/Operator.java b/src/main/java/com/esri/core/geometry/Operator.java index ffceb73f..23f6c41b 100644 --- a/src/main/java/com/esri/core/geometry/Operator.java +++ b/src/main/java/com/esri/core/geometry/Operator.java @@ -66,11 +66,16 @@ public enum Type { * a different one. If the accelerator is built for the given parameters, * the method returns immediately. * - * @param geometry - * The geometry to be accelerated - * @param spatialReference - * The spatial reference of that geometry - * @param accelDegree The acceleration degree for geometry. + * @param geometry + * The geometry to be accelerated + * + * @param spatialReference + * The spatial reference of that geometry + * + * @param accelDegree + * The acceleration degree for geometry. + * + * @return TODO */ public boolean accelerateGeometry(Geometry geometry, SpatialReference spatialReference, @@ -82,9 +87,11 @@ public boolean accelerateGeometry(Geometry geometry, /** * Returns true if the geometry can be accelerated. * - * @param geometry - * @return true for geometries that can be accelerated, false for geometries - * that cannot + * @param geometry + * under test + * + * @return {@code true} for geometries that can be accelerated, false for + * geometries that cannot */ public boolean canAccelerateGeometry(Geometry geometry) { // Override at specific Operator level diff --git a/src/main/java/com/esri/core/geometry/OperatorBuffer.java b/src/main/java/com/esri/core/geometry/OperatorBuffer.java index cca44f54..07783922 100644 --- a/src/main/java/com/esri/core/geometry/OperatorBuffer.java +++ b/src/main/java/com/esri/core/geometry/OperatorBuffer.java @@ -35,31 +35,57 @@ public Type getType() { return Type.Buffer; } - /** - *Creates a buffer around the input geometries - * - *@param inputGeometries The geometries to buffer. - *@param sr The SpatialReference of the Geometries. - *@param distances The buffer distances for the Geometries. If the size of the distances array is less than the number of geometries in the inputGeometries, the last distance value is used for the rest of geometries. - *@param bUnion If True, the buffered geometries will be unioned, otherwise they wont be unioned. - */ + /** + * Creates a buffer around the input geometries + * + * @param inputGeometries + * The geometries to buffer. + * + * @param sr + * The SpatialReference of the Geometries. + * + * @param distances + * The buffer distances for the Geometries. If the size of the + * distances array is less than the number of geometries in the + * inputGeometries, the last distance value is used for the rest of + * geometries. + * + * @param bUnion + * If True, the buffered geometries will be unioned, otherwise they + * wont be unioned. + * + * @param progressTracker + * the callback used periodically by lengthy operations + * + * @return a cursor to a collection of buffered geometries + */ public abstract GeometryCursor execute(GeometryCursor inputGeometries, - SpatialReference sr, double[] distances, boolean bUnion, - ProgressTracker progressTracker); + SpatialReference sr, double[] distances, boolean bUnion, + ProgressTracker progressTracker); - /** - *Creates a buffer around the input geometry - * - *@param inputGeometry The geometry to buffer. - *@param sr The SpatialReference of the Geometry. - *@param distance The buffer distance for the Geometry. - */ - public abstract Geometry execute(Geometry inputGeometry, - SpatialReference sr, double distance, - ProgressTracker progressTracker); + /** + * Creates a buffer around the input geometry + * + * @param inputGeometry + * The geometry to buffer. + * + * @param sr + * The SpatialReference of the Geometry. + * + * @param distance + * The buffer distance for the Geometry. + * + * @param progressTracker + * the callback used periodically by lengthy operations + * + * @return a buffered geometry from input + */ + public abstract Geometry execute(Geometry inputGeometry, + SpatialReference sr, double distance, + ProgressTracker progressTracker); - public static OperatorBuffer local() { - return (OperatorBuffer) OperatorFactoryLocal.getInstance().getOperator( - Type.Buffer); + public static OperatorBuffer local() { + return (OperatorBuffer) OperatorFactoryLocal.getInstance().getOperator( + Type.Buffer); } } diff --git a/src/main/java/com/esri/core/geometry/OperatorClip.java b/src/main/java/com/esri/core/geometry/OperatorClip.java index 8b1907af..22b2deca 100644 --- a/src/main/java/com/esri/core/geometry/OperatorClip.java +++ b/src/main/java/com/esri/core/geometry/OperatorClip.java @@ -34,22 +34,48 @@ public Type getType() { return Type.Clip; } - /** - * Performs the Clip operation on the geometry set. - */ - public abstract GeometryCursor execute(GeometryCursor geoms, - Envelope2D envelope, SpatialReference spatialRef, - ProgressTracker progressTracker); - - /** - * Performs the Clip operation on a single geometry. - */ - public abstract Geometry execute(Geometry geom, Envelope2D envelope, - SpatialReference spatialRef, ProgressTracker progressTracker); - - public static OperatorClip local() { - return (OperatorClip) OperatorFactoryLocal.getInstance().getOperator( - Type.Clip); - } + /** + * Performs the Clip operation on the geometry set. + * @param geoms + * referencing input geometries for the clip operation + * + * @param envelope + * used to clip input geometries + * + * @param spatialRef + * the geometry spatial reference + * + * @param progressTracker + * the callback used periodically by lengthy operations + * + * @return a cursor to the geometries created by clipping. + */ + public abstract GeometryCursor execute(GeometryCursor geoms, + Envelope2D envelope, SpatialReference spatialRef, + ProgressTracker progressTracker); + + /** + * Performs the Clip operation on a single geometry. + * @param geom + * input geometry for the clip operation + * + * @param envelope + * used to clip input geometries + * + * @param spatialRef + * the geometry spatial reference + * + * @param progressTracker + * the callback used periodically by lengthy operations + * + * @return The geometry created by clipping. + */ + public abstract Geometry execute(Geometry geom, Envelope2D envelope, + SpatialReference spatialRef, ProgressTracker progressTracker); + + public static OperatorClip local() { + return (OperatorClip) OperatorFactoryLocal.getInstance().getOperator( + Type.Clip); + } } diff --git a/src/main/java/com/esri/core/geometry/OperatorCut.java b/src/main/java/com/esri/core/geometry/OperatorCut.java index 762db7d6..0c406fff 100644 --- a/src/main/java/com/esri/core/geometry/OperatorCut.java +++ b/src/main/java/com/esri/core/geometry/OperatorCut.java @@ -34,14 +34,9 @@ public Type getType() { } /** - * Performs the Cut operation on a geometry. - * @param bConsiderTouch Indicates whether we consider a touch event a cut. - * This only applies to polylines, but it's recommended to set this variable to True. - * @param cuttee The input geometry to be cut. - * @param cutter The polyline that will be used to divide the cuttee into - * pieces where it crosses the cutter. - * @return Returns a GeometryCursor of cut geometries. - * All left cuts will be grouped together in the first geometry. Right cuts and + * Performs the Cut operation on a geometry. + * + * All left cuts will be grouped together in the first geometry. Right cuts and * coincident cuts are grouped in the second geometry, and each undefined cut along * with any uncut parts are output as separate geometries. If there were no cuts * the cursor will return no geometry. If the left or right cut does not @@ -49,6 +44,26 @@ public Type getType() { * undefined cut will only be produced if a left cut or right cut was * produced and there was a part left over after cutting or a cut is * bounded to the left and right of the cutter. + * + * @param bConsiderTouch + * Indicates whether we consider a touch event a cut. + * This only applies to polylines, but it's recommended to set this + * variable to True. + * + * @param cuttee + * The input geometry to be cut. + * + * @param cutter + * The polyline that will be used to divide the cuttee into pieces + * where it crosses the cutter. + * + * @param spatialReference + * The spatial reference of the input geometry + * + * @param progressTracker + * the callback used by lengthy operations + * + * @return Returns a GeometryCursor of cut geometries. */ public abstract GeometryCursor execute(boolean bConsiderTouch, Geometry cuttee, Polyline cutter, SpatialReference spatialReference, diff --git a/src/main/java/com/esri/core/geometry/OperatorDensifyByLength.java b/src/main/java/com/esri/core/geometry/OperatorDensifyByLength.java index 085dd397..bf99d269 100644 --- a/src/main/java/com/esri/core/geometry/OperatorDensifyByLength.java +++ b/src/main/java/com/esri/core/geometry/OperatorDensifyByLength.java @@ -36,45 +36,55 @@ public Type getType() { return Type.DensifyByLength; } - /** - * Performs the Densify operation on the geometry set. - * - * @param inputGeometries - * The geometries to be densified. - * @param maxLength - * The maximum segment length allowed. Must be a positive value. - * Curves are densified to straight segments using the - * maxSegmentLength. Curves are split into shorter subcurves such - * that the length of subcurves is shorter than maxSegmentLength. - * After that the curves are replaced with straight segments. - * @param progressTracker - * @return Returns the densified geometries (It does nothing to geometries - * with dim < 1, but simply passes them along). - */ - public abstract GeometryCursor execute(GeometryCursor inputGeometries, - double maxLength, ProgressTracker progressTracker); + /** + * Performs the Densify operation on the geometry set. + * + * @param inputGeometries + * The geometries to be densified. + * + * @param maxLength + * The maximum segment length allowed. Must be a positive value. + * Curves are densified to straight segments using the + * maxSegmentLength. Curves are split into shorter subcurves such + * that the length of subcurves is shorter than maxSegmentLength. + * After that the curves are replaced with straight segments. + * + * @param progressTracker + * ProgressTracker instance that is used to cancel + * the lengthy operation. Can be null. + * + * @return the densified geometries (It does nothing to geometries + * with {@literal dim < 1}, but simply passes them along). + */ + public abstract GeometryCursor execute(GeometryCursor inputGeometries, + double maxLength, ProgressTracker progressTracker); - /** - * Performs the Densify operation on the geometry set. - * - * @param inputGeometry - * The geometry to be densified. - * @param maxLength - * The maximum segment length allowed. Must be a positive value. - * Curves are densified to straight segments using the - * maxSegmentLength. Curves are split into shorter subcurves such - * that the length of subcurves is shorter than maxSegmentLength. - * After that the curves are replaced with straight segments. - * @param progressTracker - * @return Returns the densified geometry. (It does nothing to geometries - * with dim < 1, but simply passes them along). - */ - public abstract Geometry execute(Geometry inputGeometry, double maxLength, - ProgressTracker progressTracker); + /** + * Performs the Densify operation on the geometry set. + * + * @param inputGeometry + * The geometry to be densified. + * + * @param maxLength + * The maximum segment length allowed. Must be a positive value. + * Curves are densified to straight segments using the + * maxSegmentLength. Curves are split into shorter subcurves such + * that the length of subcurves is shorter than maxSegmentLength. + * After that the curves are replaced with straight segments. + * + * @param progressTracker + * ProgressTracker instance that is used to cancel + * the lengthy operation. Can be null. + * + * @return the densified geometry. (It does nothing to geometries + * with {@literal dim < 1}, but simply passes them along). + */ + public abstract Geometry execute(Geometry inputGeometry, double maxLength, + ProgressTracker progressTracker); - public static OperatorDensifyByLength local() { - return (OperatorDensifyByLength) OperatorFactoryLocal.getInstance() - .getOperator(Type.DensifyByLength); - } + public static OperatorDensifyByLength local() { + return (OperatorDensifyByLength) OperatorFactoryLocal.getInstance() + .getOperator(Type.DensifyByLength); + } } diff --git a/src/main/java/com/esri/core/geometry/OperatorDifference.java b/src/main/java/com/esri/core/geometry/OperatorDifference.java index 5e4b40e6..e756f44e 100644 --- a/src/main/java/com/esri/core/geometry/OperatorDifference.java +++ b/src/main/java/com/esri/core/geometry/OperatorDifference.java @@ -36,40 +36,56 @@ public Type getType() { return Type.Difference; } - /** - * Performs the Topological Difference operation on the geometry set. - * - * @param inputGeometries - * is the set of Geometry instances to be subtracted by the - * subtractor - * @param subtractor - * is the Geometry being subtracted. - * @return Returns the result of the subtraction. - * - * The operator subtracts subtractor from every geometry in - * inputGeometries. - */ - public abstract GeometryCursor execute(GeometryCursor inputGeometries, - GeometryCursor subtractor, SpatialReference sr, - ProgressTracker progressTracker); + /** + * Performs the Topological Difference operation on the geometry set. + * + * The operator subtracts subtractor from every geometry in + * inputGeometries. + * + * @param inputGeometries + * is the set of Geometry instances to be subtracted by the + * subtractor + * + * @param subtractor + * is the Geometry being subtracted. + * + * @param sr + * The spatial reference to get the tolerance value from. + * + * @param progressTracker + * the callback used to cancel the lengthy operation. Can be null. + * + * @return the result of the subtraction. + */ + public abstract GeometryCursor execute(GeometryCursor inputGeometries, + GeometryCursor subtractor, SpatialReference sr, + ProgressTracker progressTracker); - /** - * Performs the Topological Difference operation on the two geometries. - * - * @param inputGeometry - * is the Geometry instance on the left hand side of the - * subtraction. - * @param subtractor - * is the Geometry on the right hand side being subtracted. - * @return Returns the result of subtraction. - */ - public abstract Geometry execute(Geometry inputGeometry, - Geometry subtractor, SpatialReference sr, - ProgressTracker progressTracker); + /** + * Performs the Topological Difference operation on the two geometries. + * + * @param inputGeometry + * is the Geometry instance on the left hand side of the + * subtraction. + * + * @param subtractor + * is the Geometry on the right hand side being subtracted. + * + * @param sr + * The spatial reference to get the tolerance value from. + * + * @param progressTracker + * the callback used to cancel the lengthy operation. Can be null. + * + * @return the result of subtraction. + */ + public abstract Geometry execute(Geometry inputGeometry, + Geometry subtractor, SpatialReference sr, + ProgressTracker progressTracker); - public static OperatorDifference local() { - return (OperatorDifference) OperatorFactoryLocal.getInstance() - .getOperator(Type.Difference); - } + public static OperatorDifference local() { + return (OperatorDifference) OperatorFactoryLocal.getInstance() + .getOperator(Type.Difference); + } } diff --git a/src/main/java/com/esri/core/geometry/OperatorDistance.java b/src/main/java/com/esri/core/geometry/OperatorDistance.java index d29c2c43..991706e7 100644 --- a/src/main/java/com/esri/core/geometry/OperatorDistance.java +++ b/src/main/java/com/esri/core/geometry/OperatorDistance.java @@ -31,20 +31,29 @@ */ public abstract class OperatorDistance extends Operator { - @Override - public Type getType() { - return Type.Distance; - } - - /** - * Calculates distance between two geometries. - */ - public abstract double execute(Geometry geom1, Geometry geom2, - ProgressTracker progressTracker); - - public static OperatorDistance local() { - return (OperatorDistance) OperatorFactoryLocal.getInstance() - .getOperator(Type.Distance); - } + @Override + public Type getType() { + return Type.Distance; + } + + /** + * @param geom1 + * the first geometry of the parameter pair to be operated on. + * + * @param geom2 + * the second geometry of the parameter pair to be operated on. + * + * @param progressTracker + * the callback used to cancel the lengthy operation. Can be null. + * + * @return the distance between two geometries + */ + public abstract double execute(Geometry geom1, Geometry geom2, + ProgressTracker progressTracker); + + public static OperatorDistance local() { + return (OperatorDistance) OperatorFactoryLocal.getInstance() + .getOperator(Type.Distance); + } } diff --git a/src/main/java/com/esri/core/geometry/OperatorExportToJson.java b/src/main/java/com/esri/core/geometry/OperatorExportToJson.java index 32bfc078..0f6a8198 100644 --- a/src/main/java/com/esri/core/geometry/OperatorExportToJson.java +++ b/src/main/java/com/esri/core/geometry/OperatorExportToJson.java @@ -40,7 +40,13 @@ public Type getType() { /** * Performs the ExportToJson operation * - * @return Returns a JsonCursor. + * @param spatialReference + * the spatial reference of the input geometry + * + * @param geometryCursor + * the cursor to geometries for export + * + * @return a JsonCursor. */ public abstract JsonCursor execute(SpatialReference spatialReference, GeometryCursor geometryCursor); @@ -48,7 +54,13 @@ public abstract JsonCursor execute(SpatialReference spatialReference, /** * Performs the ExportToJson operation * - * @return Returns a String. + * @param spatialReference + * the spatial reference of the input geometry + * + * @param geometry + * the geometry to export + * + * @return a JSON String. */ public abstract String execute(SpatialReference spatialReference, Geometry geometry); @@ -56,7 +68,16 @@ public abstract String execute(SpatialReference spatialReference, /** * Performs the ExportToJson operation * - * @return Returns a String. + * @param spatialReference + * the spatial reference of the input geometry + * + * @param geometry + * the geometry to export + * + * @param exportProperties + * the export properties + * + * @return a JSON String. */ public abstract String execute(SpatialReference spatialReference, Geometry geometry, Map exportProperties); diff --git a/src/main/java/com/esri/core/geometry/OperatorExportToWkb.java b/src/main/java/com/esri/core/geometry/OperatorExportToWkb.java index fba948cb..efd261d5 100644 --- a/src/main/java/com/esri/core/geometry/OperatorExportToWkb.java +++ b/src/main/java/com/esri/core/geometry/OperatorExportToWkb.java @@ -32,33 +32,53 @@ *Export to WKB format. */ public abstract class OperatorExportToWkb extends Operator { - @Override - public Type getType() { - return Type.ExportToWkb; - } + @Override + public Type getType() { + return Type.ExportToWkb; + } - /** - * Performs the ExportToWKB operation. - * @param exportFlags Use the {@link WkbExportFlags} interface. - * @param geometry The Geometry being exported. - * @return Returns a ByteBuffer object containing the Geometry in WKB format - */ - public abstract ByteBuffer execute(int exportFlags, Geometry geometry, - ProgressTracker progressTracker); + /** + * Performs the ExportToWKB operation. + * + * @param exportFlags + * Use the {@link WkbExportFlags} interface. + * + * @param geometry + * The Geometry being exported. + * + * @param progressTracker + * the callback used periodically by lengthy operations + * + * @return a ByteBuffer object containing the Geometry in WKB format + */ + public abstract ByteBuffer execute(int exportFlags, Geometry geometry, + ProgressTracker progressTracker); - /** - * Performs the ExportToWKB operation. - * @param exportFlags Use the {@link WkbExportFlags} interface. - * @param geometry The Geometry being exported. - * @param wkbBuffer The ByteBuffer to contain the exported Geometry in WKB format. - * @return If the input buffer is null, then the size needed for the buffer is returned. Otherwise the number of bytes written to the buffer is returned. - */ - public abstract int execute(int exportFlags, Geometry geometry, - ByteBuffer wkbBuffer, ProgressTracker progressTracker); + /** + * Performs the ExportToWKB operation. + * + * @param exportFlags + * Use the {@link WkbExportFlags} interface. + * + * @param geometry + * The Geometry being exported. + * + * @param wkbBuffer + * The ByteBuffer to contain the exported Geometry in WKB format. + * + * @param progressTracker + * the callback used periodically by lengthy operations + * + * @return If the input buffer is null, then the size needed for the buffer + * is returned. Otherwise the number of bytes written to the buffer + * is returned. + */ + public abstract int execute(int exportFlags, Geometry geometry, + ByteBuffer wkbBuffer, ProgressTracker progressTracker); - public static OperatorExportToWkb local() { - return (OperatorExportToWkb) OperatorFactoryLocal.getInstance() - .getOperator(Type.ExportToWkb); - } + public static OperatorExportToWkb local() { + return (OperatorExportToWkb) OperatorFactoryLocal.getInstance() + .getOperator(Type.ExportToWkb); + } } diff --git a/src/main/java/com/esri/core/geometry/OperatorFactory.java b/src/main/java/com/esri/core/geometry/OperatorFactory.java index 66e6030a..52c931ce 100644 --- a/src/main/java/com/esri/core/geometry/OperatorFactory.java +++ b/src/main/java/com/esri/core/geometry/OperatorFactory.java @@ -31,13 +31,22 @@ *An abstract class that represent the basic OperatorFactory interface. */ public abstract class OperatorFactory { - /** - *Returns True if the given operator exists. The type is one of the Operator::Type values or a user defined value. - */ - public abstract boolean isOperatorSupported(Type type); - - /** - *Returns an operator of the given type. Throws an exception if the operator is not supported. - */ - public abstract Operator getOperator(Type type); + + /** + * @param type + * The query value + * + * @return {@code true} if the given operator exists. The type is one of + * the Operator::Type values or a user defined value. + */ + public abstract boolean isOperatorSupported(Type type); + + /** + * @param type + * The query value + * + * @return an operator of the given type. Throws an exception if the + * operator is not supported. + */ + public abstract Operator getOperator(Type type); } diff --git a/src/main/java/com/esri/core/geometry/OperatorFactoryLocal.java b/src/main/java/com/esri/core/geometry/OperatorFactoryLocal.java index f07cea96..0508b270 100644 --- a/src/main/java/com/esri/core/geometry/OperatorFactoryLocal.java +++ b/src/main/java/com/esri/core/geometry/OperatorFactoryLocal.java @@ -137,7 +137,7 @@ private OperatorFactoryLocal() { /** - *Returns a reference to the singleton. + * @return a reference to the singleton. */ public static OperatorFactoryLocal getInstance() { return INSTANCE; diff --git a/src/main/java/com/esri/core/geometry/OperatorGeneralize.java b/src/main/java/com/esri/core/geometry/OperatorGeneralize.java index ce8c4703..79cc65b4 100644 --- a/src/main/java/com/esri/core/geometry/OperatorGeneralize.java +++ b/src/main/java/com/esri/core/geometry/OperatorGeneralize.java @@ -36,7 +36,20 @@ public Type getType() { * Performs the Generalize operation on a geometry set. Point and * multipoint geometries are left unchanged. An envelope is converted to a * polygon. - * + * + * @param geoms + * the geometry set to generalize + * + * @param maxDeviation + * The max deviation + * + * @param bRemoveDegenerateParts + * {@code true} if degenerate parts should be removed + * + * @param progressTracker + * ProgressTracker instance that is used to cancel the lengthy operation. Can be null. + * + * @return a cursor the resulting geometry set */ public abstract GeometryCursor execute(GeometryCursor geoms, double maxDeviation, boolean bRemoveDegenerateParts, @@ -46,6 +59,20 @@ public abstract GeometryCursor execute(GeometryCursor geoms, * Performs the Generalize operation on a single geometry. Point and * multipoint geometries are left unchanged. An envelope is converted to a * polygon. + * + * @param geom + * the geometry to generalize + * + * @param maxDeviation + * The max deviation + * + * @param bRemoveDegenerateParts + * {@code true} if degenerate parts should be removed + * + * @param progressTracker + * ProgressTracker instance that is used to cancel the lengthy operation. Can be null. + * + * @return the resulting geometry */ public abstract Geometry execute(Geometry geom, double maxDeviation, boolean bRemoveDegenerateParts, ProgressTracker progressTracker); diff --git a/src/main/java/com/esri/core/geometry/OperatorImportFromGeoJson.java b/src/main/java/com/esri/core/geometry/OperatorImportFromGeoJson.java index 2c0c0287..51e6ec01 100644 --- a/src/main/java/com/esri/core/geometry/OperatorImportFromGeoJson.java +++ b/src/main/java/com/esri/core/geometry/OperatorImportFromGeoJson.java @@ -26,36 +26,58 @@ import org.json.JSONException; public abstract class OperatorImportFromGeoJson extends Operator { - @Override - public Type getType() { - return Type.ImportFromGeoJson; - } - - /** - * Performs the ImportFromGeoJson operation. - * @param import_flags Use the {@link GeoJsonImportFlags} interface. - * @param type Use the {@link Geometry.Type} enum. - * @param geoJsonString The string holding the Geometry in geoJson format. - * @return Returns the imported Geometry. - * @throws JSONException - */ - public abstract MapGeometry execute(int import_flags, Geometry.Type type, - String geoJsonString, ProgressTracker progress_tracker) - throws JSONException; - - /** - * Performs the ImportFromGeoJson operation. - * @param import_flags Use the {@link GeoJsonImportFlags} interface. - * @param geoJsonString The string holding the Geometry in geoJson format. - * @return Returns the imported MapOGCStructure. - * @throws JSONException - */ - public abstract MapOGCStructure executeOGC(int import_flags, - String geoJsonString, ProgressTracker progress_tracker) - throws JSONException; - - public static OperatorImportFromGeoJson local() { - return (OperatorImportFromGeoJson) OperatorFactoryLocal.getInstance() - .getOperator(Type.ImportFromGeoJson); - } + @Override + public Type getType() { + return Type.ImportFromGeoJson; + } + + /** + * Performs the ImportFromGeoJson operation. + * + * @param import_flags + * Use the {@link GeoJsonImportFlags} interface. + * + * @param type + * Use the {@link Geometry.Type} enum. + * + * @param geoJsonString + * The string holding the Geometry in geoJson format. + * + * @param progress_tracker + * Allows to cancel the operation. Can be null. + * + * @return the imported Geometry. + * + * @throws JSONException + * The JSON parse exception + */ + public abstract MapGeometry execute(int import_flags, Geometry.Type type, + String geoJsonString, ProgressTracker progress_tracker) + throws JSONException; + + /** + * Performs the ImportFromGeoJson operation. + * + * @param import_flags + * Use the {@link GeoJsonImportFlags} interface. + * + * @param geoJsonString + * The string holding the Geometry in geoJson format. + * + * @param progress_tracker + * Allows to cancel the operation. Can be null. + * + * @return the imported MapOGCStructure. + * + * @throws JSONException + * The JSON parse exception + */ + public abstract MapOGCStructure executeOGC(int import_flags, + String geoJsonString, ProgressTracker progress_tracker) + throws JSONException; + + public static OperatorImportFromGeoJson local() { + return (OperatorImportFromGeoJson) OperatorFactoryLocal.getInstance() + .getOperator(Type.ImportFromGeoJson); + } } diff --git a/src/main/java/com/esri/core/geometry/OperatorImportFromJson.java b/src/main/java/com/esri/core/geometry/OperatorImportFromJson.java index 6a88d05c..c3c42c96 100644 --- a/src/main/java/com/esri/core/geometry/OperatorImportFromJson.java +++ b/src/main/java/com/esri/core/geometry/OperatorImportFromJson.java @@ -44,29 +44,65 @@ public Type getType() { /** * Performs the ImportFromJson operation on a number of Json Strings - * - * @return Returns a MapGeometryCursor. + * + * @param type + * Use the {@link Geometry.Type} enum. + * + * @param jsonParserCursor + * a cursor to JsonParsers to use for import + * + * @return a MapGeometryCursor. */ abstract MapGeometryCursor execute(Geometry.Type type, JsonParserCursor jsonParserCursor); /** - *Performs the ImportFromJson operation on a single Json string - *@return Returns a MapGeometry. + * Performs the ImportFromJson operation on a single Json string + * + * @param type + * Use the {@link Geometry.Type} enum. + * + * @param jsonParser + * a JSON parser to use for import + * + * @return a MapGeometry. */ public abstract MapGeometry execute(Geometry.Type type, JsonParser jsonParser); /** - *Performs the ImportFromJson operation on a single Json string - *@return Returns a MapGeometry. + * Performs the ImportFromJson operation on a single Json string + * + * @param type + * Use the {@link Geometry.Type} enum. + * + * @param string + * JSON text to parse and import + * + * @return a MapGeometry. + * + * @throws JsonParseException + * the json parse exception */ public abstract MapGeometry execute(Geometry.Type type, String string) throws JsonParseException, IOException; /** *Performs the ImportFromJson operation on a JSONObject - *@return Returns a MapGeometry. + * + * @param type + * Use the {@link Geometry.Type} enum. + * + * @param jsonObject + * JSON object to import + * + * @return a MapGeometry. + * + * @throws JsonParseException + * the json parse exception + * + * @throws IOException + * the IO exception from import */ public abstract MapGeometry execute(Geometry.Type type, JSONObject jsonObject) throws JSONException, IOException; diff --git a/src/main/java/com/esri/core/geometry/OperatorImportFromWkb.java b/src/main/java/com/esri/core/geometry/OperatorImportFromWkb.java index a80e3bd9..78201968 100644 --- a/src/main/java/com/esri/core/geometry/OperatorImportFromWkb.java +++ b/src/main/java/com/esri/core/geometry/OperatorImportFromWkb.java @@ -33,33 +33,51 @@ */ public abstract class OperatorImportFromWkb extends Operator { - @Override - public Type getType() { - return Type.ImportFromWkb; - } + @Override + public Type getType() { + return Type.ImportFromWkb; + } - /** - * Performs the ImportFromWKB operation. - * @param importFlags Use the {@link WkbImportFlags} interface. - * @param type Use the {@link Geometry.Type} enum. - * @param wkbBuffer The buffer holding the Geometry in wkb format. - * @return Returns the imported Geometry. - */ - public abstract Geometry execute(int importFlags, Geometry.Type type, - ByteBuffer wkbBuffer, ProgressTracker progress_tracker); + /** + * Performs the ImportFromWKB operation. + * + * @param importFlags + * Use the {@link WkbImportFlags} interface. + * + * @param type + * Use the {@link Geometry.Type} enum. + * + * @param wkbBuffer + * The buffer holding the Geometry in wkb format. + * + * @param progress_tracker + * Allows to cancel the operation. Can be null. + * + * @return the imported Geometry. + */ + public abstract Geometry execute(int importFlags, Geometry.Type type, + ByteBuffer wkbBuffer, ProgressTracker progress_tracker); - /** - * Performs the ImportFromWkb operation. - * @param importFlags Use the {@link WkbImportFlags} interface. - * @param wkbBuffer The buffer holding the Geometry in wkb format. - * @return Returns the imported OGCStructure. - */ - public abstract OGCStructure executeOGC(int importFlags, - ByteBuffer wkbBuffer, ProgressTracker progress_tracker); + /** + * Performs the ImportFromWkb operation. + * + * @param importFlags + * Use the {@link WkbImportFlags} interface. + * + * @param wkbBuffer + * The buffer holding the Geometry in wkb format. + * + * @param progress_tracker + * Allows to cancel the operation. Can be null. + * + * @return the imported OGCStructure. + */ + public abstract OGCStructure executeOGC(int importFlags, + ByteBuffer wkbBuffer, ProgressTracker progress_tracker); - public static OperatorImportFromWkb local() { - return (OperatorImportFromWkb) OperatorFactoryLocal.getInstance() - .getOperator(Type.ImportFromWkb); - } + public static OperatorImportFromWkb local() { + return (OperatorImportFromWkb) OperatorFactoryLocal.getInstance() + .getOperator(Type.ImportFromWkb); + } } diff --git a/src/main/java/com/esri/core/geometry/OperatorImportFromWkt.java b/src/main/java/com/esri/core/geometry/OperatorImportFromWkt.java index 60b0460d..2fd34f12 100644 --- a/src/main/java/com/esri/core/geometry/OperatorImportFromWkt.java +++ b/src/main/java/com/esri/core/geometry/OperatorImportFromWkt.java @@ -26,33 +26,51 @@ import com.esri.core.geometry.Operator.Type; public abstract class OperatorImportFromWkt extends Operator { - @Override - public Type getType() { - return Type.ImportFromWkb; - } - - /** - * Performs the ImportFromWkt operation. - * @param import_flags Use the {@link WktImportFlags} interface. - * @param type Use the {@link Geometry.Type} enum. - * @param wkt_string The string holding the Geometry in wkt format. - * @return Returns the imported Geometry. - */ - public abstract Geometry execute(int import_flags, Geometry.Type type, - String wkt_string, ProgressTracker progress_tracker); - - /** - * Performs the ImportFromWkt operation. - * @param import_flags Use the {@link WktImportFlags} interface. - * @param wkt_string The string holding the Geometry in wkt format. - * @return Returns the imported OGCStructure. - */ - public abstract OGCStructure executeOGC(int import_flags, - String wkt_string, ProgressTracker progress_tracker); - - public static OperatorImportFromWkt local() { - return (OperatorImportFromWkt) OperatorFactoryLocal.getInstance() - .getOperator(Type.ImportFromWkt); - } + @Override + public Type getType() { + return Type.ImportFromWkb; + } + + /** + * Performs the ImportFromWkt operation. + * + * @param import_flags + * Use the {@link WktImportFlags} interface. + * + * @param type + * Use the {@link Geometry.Type} enum. + * + * @param wkt_string + * The string holding the Geometry in wkt format. + * + * @param progress_tracker + * Allows to cancel the operation. Can be null. + * + * @return the imported Geometry. + */ + public abstract Geometry execute(int import_flags, Geometry.Type type, + String wkt_string, ProgressTracker progress_tracker); + + /** + * Performs the ImportFromWkt operation. + * + * @param import_flags + * Use the {@link WktImportFlags} interface. + * + * @param wkt_string + * The string holding the Geometry in wkt format. + * + * @param progress_tracker + * Allows to cancel the operation. Can be null. + * + * @return the imported OGCStructure. + */ + public abstract OGCStructure executeOGC(int import_flags, + String wkt_string, ProgressTracker progress_tracker); + + public static OperatorImportFromWkt local() { + return (OperatorImportFromWkt) OperatorFactoryLocal.getInstance() + .getOperator(Type.ImportFromWkt); + } } diff --git a/src/main/java/com/esri/core/geometry/OperatorIntersection.java b/src/main/java/com/esri/core/geometry/OperatorIntersection.java index 2f23f11c..33b878b7 100644 --- a/src/main/java/com/esri/core/geometry/OperatorIntersection.java +++ b/src/main/java/com/esri/core/geometry/OperatorIntersection.java @@ -36,56 +36,119 @@ public Type getType() { } /** - *Performs the Topological Intersection operation on the geometry set. - *@param inputGeometries is the set of Geometry instances to be intersected by the intersector. - *@param intersector is the intersector Geometry. + * Performs the Topological Intersection operation on the geometry set. * - *The operator intersects every geometry in the inputGeometries with the first geometry of the intersector and returns the result. + * The operator intersects every geometry in the inputGeometries with the + * first geometry of the intersector and returns the result. + * + * @param inputGeometries + * is the set of Geometry instances to be intersected by the + * intersector. + * + * @param intersector + * is the intersector Geometry. + * + * @param sr + * The spatial reference is used to get tolerance value. Can be + * null, then the tolerance is not used and the operation is + * performed with a small tolerance value just enough to make the + * operation robust. + * + * @param progressTracker + * Allows cancellation of a long operation. Can be null. + * + * @return the cursor of the intersection result. */ public abstract GeometryCursor execute(GeometryCursor inputGeometries, GeometryCursor intersector, SpatialReference sr, ProgressTracker progressTracker); /** - *Performs the Topological intersection operation on the geometry set. - *@param input_geometries is the set of Geometry instances to be intersected by the intersector. - *@param intersector is the intersector Geometry. Only single intersector is used, therefore, the intersector.next() is called only once. - *@param sr The spatial reference is used to get tolerance value. Can be null, then the tolerance is not used and the operation is performed with - *a small tolerance value just enough to make the operation robust. - *@param progress_tracker Allows to cancel the operation. Can be null. - *@param dimensionMask The dimension of the intersection. The value is either -1, or a bitmask mask of values (1 << dim). - *The value of -1 means the lower dimension in the intersecting pair. - *This is a fastest option when intersecting polygons with polygons or polylines. - *The bitmask of values (1 << dim), where dim is the desired dimension value, is used to indicate - *what dimensions of geometry one wants to be returned. For example, to return - *multipoints and lines only, pass (1 << 0) | (1 << 1), which is equivalen to 1 | 2, or 3. - *@return Returns the cursor of the intersection result. The cursors' get_geometry_ID method returns the current ID of the input geometry - *being processed. Wh dimensionMask is a bitmask, there will be n result geometries per one input geometry returned, where n is the number - *of bits set in the bitmask. For example, if the dimensionMask is 5, there will be two geometries per one input geometry. - * - *The operator intersects every geometry in the input_geometries with the first geometry of the intersector and returns the result. - * - *Note, when the dimensionMask is -1, then for each intersected pair of geometries, - *the result has the lower of dimentions of the two geometries. That is, the dimension of the Polyline/Polyline intersection - *is always 1 (that is, for polylines it never returns crossing points, but the overlaps only). - *If dimensionMask is 7, the operation will return any possible + * Performs the Topological intersection operation on the geometry set. + * + * The operator intersects every geometry in the input_geometries with the + * first geometry of the intersector and returns the result. + * + * Note, when the dimensionMask is -1, then for each intersected pair of + * geometries, the result has the lower of dimentions of the two + * geometries. That is, the dimension of the Polyline/Polyline intersection + * is always 1 (that is, for polylines it never returns crossing points, + * but the overlaps only). + * If dimensionMask is 7, the operation will return any possible. + * + * @param input_geometries + * is the set of Geometry instances to be intersected by the + * intersector. + * + * @param intersector + * is the intersector Geometry. Only single intersector is used, + * therefore, the intersector.next() is called only once. + * + * @param sr + * The spatial reference is used to get tolerance value. Can be + * null, then the tolerance is not used and the operation is + * performed with a small tolerance value just enough to make the + * operation robust. + * + * @param progress_tracker + * Allows to cancel the operation. Can be null. + * + * @param dimensionMask + * The dimension of the intersection. The value is either -1, or a + * bitmask mask of values {@literal(1 << dim)}. + * The value of -1 means the lower dimension in the intersecting + * pair. + * This is a fastest option when intersecting polygons with + * polygons or polylines. + * The bitmask of values {@literal (1 << dim)}, where dim is the + * desired dimension value, is used to indicate what dimensions of + * geometry one wants to be returned. For example, to return + * multipoints and lines only, pass {@literal (1 << 0) | (1 << 1)}, + * which is equivalent to 1 | 2, or 3. + * + * @return the cursor of the intersection result. The cursors' + * get_geometry_ID method returns the current ID of the input + * geometry being processed. Wh dimensionMask is a bitmask, there + * will be n result geometries per one input geometry returned, + * where n is the number of bits set in the bitmask. For example, + * if the dimensionMask is 5, there will be two geometries per one + * input geometry. */ public abstract GeometryCursor execute(GeometryCursor input_geometries, GeometryCursor intersector, SpatialReference sr, ProgressTracker progress_tracker, int dimensionMask); /** - *Performs the Topological Intersection operation on the geometry. - *The result has the lower of dimentions of the two geometries. That is, the dimension of the - *Polyline/Polyline intersection is always 1 (that is, for polylines it never returns crossing - *points, but the overlaps only). - *The call is equivalent to calling the overloaded method using cursors: - *execute(new SimpleGeometryCursor(input_geometry), new SimpleGeometryCursor(intersector), sr, progress_tracker, mask).next(); - *where mask can be either -1 or min(1 << input_geometry.getDimension(), 1 << intersector.getDimension()); - *@param inputGeometry is the Geometry instance to be intersected by the intersector. - *@param intersector is the intersector Geometry. - *@param sr The spatial reference to get the tolerance value from. Can be null, then the tolerance is calculated from the input geometries. - *@return Returns the intersected Geometry. + * Performs the Topological Intersection operation on the geometry. + * + * The result has the lower of dimensions of the two geometries. That is, + * the dimension of the Polyline/Polyline intersection is always 1 (that + * is, for polylines it never returns crossing points, but the overlaps + * only). + * The call is equivalent to calling the overloaded method using cursors: + * {@code execute(new SimpleGeometryCursor(input_geometry), + * new SimpleGeometryCursor(intersector), sr, progress_tracker, + * mask).next(); + * execute(new SimpleGeometryCursor(input_geometry), + * new SimpleGeometryCursor(intersector), sr, progress_tracker, + * mask).next();} + * where mask can be either + * {@literal -1 or min(1 << input_geometry.getDimension(), + * 1 << intersector.getDimension());} + * + * @param inputGeometry + * is the Geometry instance to be intersected by the intersector. + * + * @param intersector + * is the intersector Geometry. + * + * @param sr + * The spatial reference to get the tolerance value from. Can be null, then the tolerance is calculated from the input geometries. + * + * @param progressTracker + * Allows cancellation of a long operation. Can be null. + * + * @return the intersected Geometry. */ public abstract Geometry execute(Geometry inputGeometry, Geometry intersector, SpatialReference sr, diff --git a/src/main/java/com/esri/core/geometry/OperatorOffset.java b/src/main/java/com/esri/core/geometry/OperatorOffset.java index 7b4f3673..5f2d3cf7 100644 --- a/src/main/java/com/esri/core/geometry/OperatorOffset.java +++ b/src/main/java/com/esri/core/geometry/OperatorOffset.java @@ -40,37 +40,46 @@ public enum JoinType { /** * Creates offset version of the input geometries. - * + * * The offset operation creates a geometry that is a constant distance from * an input polyline or polygon. It is similar to buffering, but produces a - * one sided result. If offsetDistance > 0, then the offset geometry is - * constructed to the right of the oriented input geometry, otherwise it is - * constructed to the left. For a simple polygon, the orientation of outer - * rings is clockwise and for inner rings it is counter clockwise. So the - * "right side" of a simple polygon is always its inside. The bevelRatio is - * multiplied by the offset distance and the result determines how far a - * mitered offset intersection can be from the input curve before it is - * beveled. - * - * @param inputGeometries - * The geometries to calculate offset for. Point and MultiPoint - * are not supported. - * @param sr - * The SpatialReference of the Geometries. - * @param distance - * The offset distance for the Geometries. - * @param joins - * The join type of the offset geometry. - * @param bevelRatio - * The ratio used to produce a bevel join instead of a miter join - * (used only when joins is Miter) - * @param flattenError - * The maximum distance of the resulting segments compared to the - * true circular arc (used only when joins is Round). If - * flattenError is 0, tolerance value is used. Also, the - * algorithm never produces more than around 180 vertices for - * each round join. - * @return Returns the result of the offset operation. + * one sided result. If {@literal offsetDistance > 0}, then the offset + * geometry is constructed to the right of the oriented input geometry, + * otherwise it is constructed to the left. For a simple polygon, the + * orientation of outer rings is clockwise and for inner rings it is + * counter clockwise. So the "right side" of a simple polygon is always its + * inside. The bevelRatio is multiplied by the offset distance and the + * result determines how far a mitered offset intersection can be from the + * input curve before it is beveled. + * + * @param inputGeometries + * The geometries to calculate offset for. Point and MultiPoint + * are not supported. + * + * @param sr + * The SpatialReference of the Geometries. + * + * @param distance + * The offset distance for the Geometries. + * + * @param joins + * The join type of the offset geometry. + * + * @param bevelRatio + * The ratio used to produce a bevel join instead of a miter join + * (used only when joins is Miter) + * + * @param flattenError + * The maximum distance of the resulting segments compared to the + * true circular arc (used only when joins is Round). If + * flattenError is 0, tolerance value is used. Also, the + * algorithm never produces more than around 180 vertices for + * each round join. + * + * @param progressTracker + * Allows cancellation of a long operation. Can be null. + * + * @return the result of the offset operation. */ public abstract GeometryCursor execute(GeometryCursor inputGeometries, SpatialReference sr, double distance, JoinType joins, @@ -79,37 +88,46 @@ public abstract GeometryCursor execute(GeometryCursor inputGeometries, /** * Creates offset version of the input geometry. - * + * * The offset operation creates a geometry that is a constant distance from * an input polyline or polygon. It is similar to buffering, but produces a - * one sided result. If offsetDistance > 0, then the offset geometry is - * constructed to the right of the oriented input geometry, otherwise it is - * constructed to the left. For a simple polygon, the orientation of outer - * rings is clockwise and for inner rings it is counter clockwise. So the - * "right side" of a simple polygon is always its inside. The bevelRatio is - * multiplied by the offset distance and the result determines how far a - * mitered offset intersection can be from the input curve before it is - * beveled. - * - * @param inputGeometry - * The geometry to calculate offset for. Point and MultiPoint are - * not supported. - * @param sr - * The SpatialReference of the Geometries. - * @param distance - * The offset distance for the Geometries. - * @param joins - * The join type of the offset geometry. - * @param bevelRatio - * The ratio used to produce a bevel join instead of a miter join - * (used only when joins is Miter) - * @param flattenError - * The maximum distance of the resulting segments compared to the - * true circular arc (used only when joins is Round). If - * flattenError is 0, tolerance value is used. Also, the - * algorithm never produces more than around 180 vetices for each - * round join. - * @return Returns the result of the offset operation. + * one sided result. If {@literal offsetDistance > 0}, then the offset + * geometry is constructed to the right of the oriented input geometry, + * otherwise it is constructed to the left. For a simple polygon, the + * orientation of outer rings is clockwise and for inner rings it is + * counter clockwise. So the "right side" of a simple polygon is always its + * inside. The bevelRatio is multiplied by the offset distance and the + * result determines how far a mitered offset intersection can be from the + * input curve before it is beveled. + * + * @param inputGeometry + * The geometry to calculate offset for. Point and MultiPoint are + * not supported. + * + * @param sr + * The SpatialReference of the Geometries. + * + * @param distance + * The offset distance for the Geometries. + * + * @param joins + * The join type of the offset geometry. + * + * @param bevelRatio + * The ratio used to produce a bevel join instead of a miter join + * (used only when joins is Miter) + * + * @param flattenError + * The maximum distance of the resulting segments compared to the + * true circular arc (used only when joins is Round). If + * flattenError is 0, tolerance value is used. Also, the + * algorithm never produces more than around 180 vetices for each + * round join. + * + * @param progressTracker + * Allows cancellation of a long operation. Can be null. + * + * @return the result of the offset operation. */ public abstract Geometry execute(Geometry inputGeometry, SpatialReference sr, double distance, JoinType joins, diff --git a/src/main/java/com/esri/core/geometry/OperatorProximity2D.java b/src/main/java/com/esri/core/geometry/OperatorProximity2D.java index 7449fc95..158b8ae8 100644 --- a/src/main/java/com/esri/core/geometry/OperatorProximity2D.java +++ b/src/main/java/com/esri/core/geometry/OperatorProximity2D.java @@ -36,33 +36,61 @@ public Type getType() { } /** - *Returns the nearest coordinate on the Geometry to the given input point. - *@param geom The input Geometry. - *@param inputPoint The query point. - *@param bTestPolygonInterior When true and geom is a polygon, the function will test if the input_point is inside of the polygon. Points that are - *inside of the polygon have zero distance to the polygon. When false, the function will not check if the point is inside of the polygon, - *but only determine proximity to the boundary. - *@param bCalculateLeftRightSide The function will calculate left/right side of polylines or polygons when the parameter is True. - *\return Returns the result of proximity calculation. See Proximity_2D_result. + * Returns the nearest coordinate on the Geometry to the given input point. + * + * @param geom + * The input Geometry. + * + * @param inputPoint + * The query point. + * + * @param bTestPolygonInterior + * When true and geom is a polygon, the function will test if + * the input_point is inside of the polygon. Points that are + * inside of the polygon have zero distance to the polygon. + * When false, the function will not check if the point is + * inside of the polygon but only determine proximity to the + * boundary. + * + * @param bCalculateLeftRightSide + * The function will calculate left/right side of polylines or + * polygons when the parameter is True. + * + * @return the result of proximity calculation. See {@link Proximity2DResult}. */ public abstract Proximity2DResult getNearestCoordinate(Geometry geom, Point inputPoint, boolean bTestPolygonInterior, boolean bCalculateLeftRightSide); /** - *Returns the nearest coordinate on the Geometry to the given input point. - *@param geom The input Geometry. - *@param inputPoint The query point. - *@param bTestPolygonInterior When true and geom is a polygon, the function will test if the input_point is inside of the polygon. Points that are - *inside of the polygon have zero distance to the polygon. When false, the function will not check if the point is inside of the polygon, - *but only determine proximity to the boundary. - *\return Returns the result of proximity calculation. See Proximity_2D_result. + * Returns the nearest coordinate on the Geometry to the given input point. + * + * @param geom + * The input Geometry. + * + * @param inputPoint + * The query point. + * + * @param bTestPolygonInterior + * When true and geom is a polygon, the function will test if + * the input_point is inside of the polygon. Points that are + * inside of the polygon have zero distance to the polygon. When + * false, the function will not check if the point is inside of + * the polygon, but only determine proximity to the boundary. + * + * @return the result of proximity calculation. See Proximity_2D_result. */ public abstract Proximity2DResult getNearestCoordinate(Geometry geom, Point inputPoint, boolean bTestPolygonInterior); /** - * Returns the nearest vertex of the Geometry to the given input point. + * @param geom + * The input Geometry. + * + * @param inputPoint + * The query point. + * + * @return the nearest vertex of the Geometry to the given input point. */ public abstract Proximity2DResult getNearestVertex(Geometry geom, Point inputPoint); @@ -71,15 +99,19 @@ public abstract Proximity2DResult getNearestVertex(Geometry geom, * Returns vertices of the Geometry that are closer to the given point than * the given radius. * - * @param geom - * The input Geometry. - * @param inputPoint - * The query point. - * @param searchRadius - * The maximum distance to the query point of the vertices. - * @param maxVertexCountToReturn - * The maximum vertex count to return. The function returns no - * more than this number of vertices. + * @param geom + * The input Geometry. + * + * @param inputPoint + * The query point. + * + * @param searchRadius + * The maximum distance to the query point of the vertices. + * + * @param maxVertexCountToReturn + * The maximum vertex count to return. The function returns no + * more than this number of vertices. + * * @return The array of vertices that are in the given search radius to the * point. The array is sorted by distance to the queryPoint with the * closest point first. When there are more than the diff --git a/src/main/java/com/esri/core/geometry/OperatorRelate.java b/src/main/java/com/esri/core/geometry/OperatorRelate.java index d5542990..3c598aa0 100644 --- a/src/main/java/com/esri/core/geometry/OperatorRelate.java +++ b/src/main/java/com/esri/core/geometry/OperatorRelate.java @@ -37,14 +37,26 @@ public Type getType() { return Type.Relate; } - /** - *Performs the Relation operation between two geometries using the DE-9IM matrix encoded as a string. - *@param inputGeom1 The first geometry in the relation. - *@param inputGeom2 The second geometry in the relation. - *@param sr The spatial reference of the geometries. - *@param de_9im_string The DE-9IM matrix relation encoded as a string. - *@return Returns True if the relation holds, False otherwise. - */ + /** + * Performs the Relation operation between two geometries using the DE-9IM matrix encoded as a string. + * + * @param inputGeom1 + * The first geometry in the relation. + * + * @param inputGeom2 + * The second geometry in the relation. + * + * @param sr + * The spatial reference of the geometries. + * + * @param de_9im_string + * The DE-9IM matrix relation encoded as a string. + * + * @param progressTracker + * the callback used by lengthy operations + * + * @return {@code true} if the relation holds, False otherwise. + */ public abstract boolean execute(Geometry inputGeom1, Geometry inputGeom2, SpatialReference sr, String de_9im_string, ProgressTracker progressTracker); @@ -52,7 +64,7 @@ public static OperatorRelate local() { return (OperatorRelate) OperatorFactoryLocal.getInstance().getOperator( Type.Relate); } - + @Override public boolean canAccelerateGeometry(Geometry geometry) { return RelationalOperations.Accelerate_helper @@ -65,6 +77,6 @@ public boolean accelerateGeometry(Geometry geometry, GeometryAccelerationDegree accelDegree) { return RelationalOperations.Accelerate_helper.accelerate_geometry( geometry, spatialReference, accelDegree); - } + } } diff --git a/src/main/java/com/esri/core/geometry/OperatorSimpleRelation.java b/src/main/java/com/esri/core/geometry/OperatorSimpleRelation.java index 1a08cf6d..39c98d7e 100644 --- a/src/main/java/com/esri/core/geometry/OperatorSimpleRelation.java +++ b/src/main/java/com/esri/core/geometry/OperatorSimpleRelation.java @@ -31,25 +31,37 @@ */ public abstract class OperatorSimpleRelation extends Operator { - /** - * Performs the given relation operation between two geometries. - * - * @return Returns True if the relation holds, False otherwise. - */ - public abstract boolean execute(Geometry inputGeom1, Geometry inputGeom2, - SpatialReference sr, ProgressTracker progressTracker); - - @Override - public boolean canAccelerateGeometry(Geometry geometry) { - return RelationalOperations.Accelerate_helper - .can_accelerate_geometry(geometry); - } - - @Override - public boolean accelerateGeometry(Geometry geometry, - SpatialReference spatialReference, - GeometryAccelerationDegree accelDegree) { - return RelationalOperations.Accelerate_helper.accelerate_geometry( - geometry, spatialReference, accelDegree); - } + /** + * Performs the given relation operation between two geometries. + * + * @param inputGeom1 + * first input + * + * @param inputGeom2 + * second input + * + * @param sr + * for the given input geometries + * + * @param progressTracker + * the callback used for length operations + * + * @return {@code true} if the relation holds, false otherwise. + */ + public abstract boolean execute(Geometry inputGeom1, Geometry inputGeom2, + SpatialReference sr, ProgressTracker progressTracker); + + @Override + public boolean canAccelerateGeometry(Geometry geometry) { + return RelationalOperations.Accelerate_helper + .can_accelerate_geometry(geometry); + } + + @Override + public boolean accelerateGeometry(Geometry geometry, + SpatialReference spatialReference, + GeometryAccelerationDegree accelDegree) { + return RelationalOperations.Accelerate_helper.accelerate_geometry( + geometry, spatialReference, accelDegree); + } } diff --git a/src/main/java/com/esri/core/geometry/OperatorSimplify.java b/src/main/java/com/esri/core/geometry/OperatorSimplify.java index 3e9beca9..86cc5922 100644 --- a/src/main/java/com/esri/core/geometry/OperatorSimplify.java +++ b/src/main/java/com/esri/core/geometry/OperatorSimplify.java @@ -46,25 +46,47 @@ public Operator.Type getType() { } /** - *Tests if the Geometry is simple. - *@param geom The Geometry to be tested. - *@param spatialRef Spatial reference from which the tolerance is obtained. Can be null, then a - *very small tolerance value is derived from the geometry bounds. - *@param bForceTest When True, the Geometry will be tested regardless of the internal IsKnownSimple flag. - *@param result if not null, will contain the results of the check. - *@param progressTracker Allows cancellation of a long operation. Can be null. - **/ + * Tests if the Geometry is simple. + * + * @param geom + * The Geometry to be tested. + * + * @param spatialRef + * Spatial reference from which the tolerance is obtained. Can be + * null, then a very small tolerance value is derived from the + * geometry bounds. + * + * @param bForceTest + * When True, the Geometry will be tested regardless of the + * internal IsKnownSimple flag. + * + * @param result + * if not null, will contain the results of the check. + * + * @param progressTracker + * Allows cancellation of a long operation. Can be null. + * + * @return {@code true} if the geometry is simple + */ public abstract boolean isSimpleAsFeature(Geometry geom, SpatialReference spatialRef, boolean bForceTest, NonSimpleResult result, ProgressTracker progressTracker); /** - *Tests if the Geometry is simple (second call will use a cached IsKnownSimple flag and immediately return). - *@param geom The Geometry to be tested. - *@param spatialRef Spatial reference from which the tolerance is obtained. Can be null, then a - *very small tolerance value is derived from the geometry bounds. - *@param progressTracker Allows cancellation of a long operation. Can be null. + * Tests if the Geometry is simple (second call will use a cached IsKnownSimple flag and immediately return). + * + * @param geom + * The Geometry to be tested. + * + * @param spatialRef + * Spatial reference from which the tolerance is obtained. Can be + * null, then a very small tolerance value is derived from the + * geometry bounds. * + * @param progressTracker + * Allows cancellation of a long operation. Can be null. + * + * @return {@code true} if the geometry is simple */ public boolean isSimpleAsFeature(Geometry geom, SpatialReference spatialRef, ProgressTracker progressTracker) { @@ -72,30 +94,52 @@ public boolean isSimpleAsFeature(Geometry geom, } /** - *Performs the Simplify operation on the geometry cursor. - *@param geoms Geometries to simplify. - *@param sr Spatial reference from which the tolerance is obtained. When null, the tolerance - *will be derived individually for each geometry from its bounds. - *@param bForceSimplify When True, the Geometry will be simplified regardless of the internal IsKnownSimple flag. - *@param progressTracker Allows cancellation of a long operation. Can be null. - *@return Returns a GeometryCursor of simplified geometries. - * - *The isSimpleAsFeature returns true after this method. + * Performs the Simplify operation on the geometry cursor. + * + * The isSimpleAsFeature returns true after this method. + * + * @param geoms + * Geometries to simplify. + * + * @param sr + * Spatial reference from which the tolerance is obtained. When + * null, the tolerance will be derived individually for each + * geometry from its bounds. + * + * @param bForceSimplify + * When True, the Geometry will be simplified regardless of the + * internal IsKnownSimple flag. + * + * @param progressTracker + * Allows cancellation of a long operation. Can be null. + * + * @return a GeometryCursor of simplified geometries. */ public abstract GeometryCursor execute(GeometryCursor geoms, SpatialReference sr, boolean bForceSimplify, ProgressTracker progressTracker); /** - *Performs the Simplify operation on the geometry. - *@param geom Geometry to simplify. - *@param sr Spatial reference from which the tolerance is obtained. When null, the tolerance - *will be derived individually for each geometry from its bounds. - *@param bForceSimplify When True, the Geometry will be simplified regardless of the internal IsKnownSimple flag. - *@param progressTracker Allows cancellation of a long operation. Can be null. - *@return Returns a simple geometry. - * - *The isSimpleAsFeature returns true after this method. + * Performs the Simplify operation on the geometry. + * + * The isSimpleAsFeature returns true after this method. + * + * @param geom + * Geometry to simplify. + * + * @param sr + * Spatial reference from which the tolerance is obtained. When + * null, the tolerance will be derived individually for each + * geometry from its bounds. + * + * @param bForceSimplify + * When True, the Geometry will be simplified regardless of the + * internal IsKnownSimple flag. + * + * @param progressTracker + * Allows cancellation of a long operation. Can be null. + * + * @return a simple geometry. */ public abstract Geometry execute(Geometry geom, SpatialReference sr, boolean bForceSimplify, ProgressTracker progressTracker); diff --git a/src/main/java/com/esri/core/geometry/OperatorSimplifyOGC.java b/src/main/java/com/esri/core/geometry/OperatorSimplifyOGC.java index c04ba0c4..f455b028 100644 --- a/src/main/java/com/esri/core/geometry/OperatorSimplifyOGC.java +++ b/src/main/java/com/esri/core/geometry/OperatorSimplifyOGC.java @@ -36,17 +36,34 @@ public Operator.Type getType() { } /** - *Tests if the Geometry is simple for OGC specification. - *@param geom The Geometry to be tested. - *@param spatialRef Spatial reference to obtain the tolerance from. When null, the tolerance - *will be derived individually from geometry bounds. - *@param bForceTest When True, the Geometry will be tested regardless of the IsKnownSimple flag. - *@param progressTracker Allows cancellation of a long operation. Can be null. + * Tests if the Geometry is simple for OGC specification. * - *Note: As other methods in the OperatorSimplifyOGC, this method uses tolerance from the spatial reference. - *Points that are within the tolerance are considered equal. + * Note: As other methods in the OperatorSimplifyOGC, this method uses + * tolerance from the spatial reference. + * Points that are within the tolerance are considered equal. * - *When this method returns true, the OperatorSimplify.isSimpleAsFeature will return true also (this does not necessary happen the other way around). + * When this method returns true, the OperatorSimplify.isSimpleAsFeature + * will return true also (this does not necessary happen the other way + * around). + * + * @param geom + * The Geometry to be tested. + * + * @param spatialRef + * Spatial reference to obtain the tolerance from. When null, the tolerance + * will be derived individually from geometry bounds. + * + * @param bForceTest + * When True, the Geometry will be tested regardless of the + * IsKnownSimple flag. + * + * @param result + * The non simple result TODO + * + * @param progressTracker + * Allows cancellation of a long operation. Can be null. + * + * @return {@code true} if the Geometry is simple according to the OGC specification. */ public abstract boolean isSimpleOGC(Geometry geom, SpatialReference spatialRef, boolean bForceTest, @@ -54,14 +71,25 @@ public abstract boolean isSimpleOGC(Geometry geom, /** * Processes geometry cursor to ensure its geometries are simple for OGC specification. - * @param geoms Geometries to be simplified. - * @param sr Spatial reference to obtain the tolerance from. When null, the tolerance - * will be derived individually for each geometry from its bounds. - * @param bForceSimplify When True, the Geometry will be simplified regardless of the internal IsKnownSimple flag. - * @param progressTracker Allows cancellation of a long operation. Can be null. - * @return Returns a GeometryCursor of simplified geometries. - * + * * The isSimpleOGC returns true after this call. + * + * @param geoms + * Geometries to be simplified. + * + * @param sr + * Spatial reference to obtain the tolerance from. When null, the + * tolerance will be derived individually for each geometry from + * its bounds. + * + * @param bForceSimplify + * When True, the Geometry will be simplified regardless of the + * internal IsKnownSimple flag. + * + * @param progressTracker + * Allows cancellation of a long operation. Can be null. + * + * @return a GeometryCursor of simplified geometries. */ public abstract GeometryCursor execute(GeometryCursor geoms, SpatialReference sr, boolean bForceSimplify, @@ -69,14 +97,25 @@ public abstract GeometryCursor execute(GeometryCursor geoms, /** * Processes geometry to ensure it is simple for OGC specification. - * @param geom The geometry to be simplified. - * @param sr Spatial reference to obtain the tolerance from. When null, the tolerance - * will be derived individually from geometry bounds. - * @param bForceSimplify When True, the Geometry will be simplified regardless of the internal IsKnownSimple flag. - * @param progressTracker Allows cancellation of a long operation. Can be null. - * @return Returns a simple Geometry that should be visually equivalent to the input geometry. - * + * * The isSimpleOGC returns true after this call. + * + * @param geom + * The geometry to be simplified. + * + * @param sr + * Spatial reference to obtain the tolerance from. When null, the + * tolerance will be derived individually from geometry bounds. + * + * @param bForceSimplify + * When True, the Geometry will be simplified regardless of the + * internal IsKnownSimple flag. + * + * @param progressTracker + * Allows cancellation of a long operation. Can be null. + * + * @return a simple Geometry that should be visually equivalent to the + * input geometry. */ public abstract Geometry execute(Geometry geom, SpatialReference sr, boolean bForceSimplify, ProgressTracker progressTracker); diff --git a/src/main/java/com/esri/core/geometry/OperatorSymmetricDifference.java b/src/main/java/com/esri/core/geometry/OperatorSymmetricDifference.java index ea84ce0c..ce1bf0b0 100644 --- a/src/main/java/com/esri/core/geometry/OperatorSymmetricDifference.java +++ b/src/main/java/com/esri/core/geometry/OperatorSymmetricDifference.java @@ -30,36 +30,52 @@ * */ public abstract class OperatorSymmetricDifference extends Operator implements CombineOperator { - @Override - public Type getType() { - return Type.Difference; - } + @Override + public Type getType() { + return Type.Difference; + } - /** - *Performs the Symmetric Difference operation on the geometry set. - *@param inputGeometries is the set of Geometry instances to be XOR'd by rightGeometry. - *@param rightGeometry is the Geometry being XOR'd with the inputGeometies. - *@return Returns the result of the symmetric difference. - * - *The operator XOR's every geometry in inputGeometries with rightGeometry. - */ - public abstract GeometryCursor execute(GeometryCursor inputGeometries, - GeometryCursor rightGeometry, SpatialReference sr, - ProgressTracker progressTracker); + /** + * Performs the Symmetric Difference operation on the geometry set. + * + * The operator XOR's every geometry in inputGeometries with rightGeometry. + * + * @param inputGeometries + * is the set of Geometry instances to be XOR'd by rightGeometry. + * + * @param rightGeometry + * is the Geometry being XOR'd with the inputGeometies. + * + * @param sr + * the spatial reference of the input geometries + * + * @param progressTracker + * the callback used by lengthy operations + * + * @return the result of the symmetric difference. + */ + public abstract GeometryCursor execute(GeometryCursor inputGeometries, + GeometryCursor rightGeometry, SpatialReference sr, + ProgressTracker progressTracker); - /** - *Performs the Symmetric Difference operation on the two geometries. - *@param leftGeometry is one of the Geometry instances in the XOR operation. - *@param rightGeometry is one of the Geometry instances in the XOR operation. - *@return Returns the result of the symmetric difference. - */ - public abstract Geometry execute(Geometry leftGeometry, - Geometry rightGeometry, SpatialReference sr, - ProgressTracker progressTracker); + /** + *Performs the Symmetric Difference operation on the two geometries. + * + *@param leftGeometry + * is one of the Geometry instances in the XOR operation. + * + *@param rightGeometry + * is one of the Geometry instances in the XOR operation. + * + *@return the result of the symmetric difference. + */ + public abstract Geometry execute(Geometry leftGeometry, + Geometry rightGeometry, SpatialReference sr, + ProgressTracker progressTracker); - public static OperatorSymmetricDifference local() { - return (OperatorSymmetricDifference) OperatorFactoryLocal.getInstance() - .getOperator(Type.SymmetricDifference); - } + public static OperatorSymmetricDifference local() { + return (OperatorSymmetricDifference) OperatorFactoryLocal.getInstance() + .getOperator(Type.SymmetricDifference); + } } diff --git a/src/main/java/com/esri/core/geometry/OperatorUnion.java b/src/main/java/com/esri/core/geometry/OperatorUnion.java index 8a0a8601..38f5c023 100644 --- a/src/main/java/com/esri/core/geometry/OperatorUnion.java +++ b/src/main/java/com/esri/core/geometry/OperatorUnion.java @@ -32,30 +32,45 @@ * */ public abstract class OperatorUnion extends Operator implements CombineOperator{ - @Override - public Type getType() { - return Type.Union; - } - - /** - *Performs the Topological Union operation on the geometry set. - *@param inputGeometries is the set of Geometry instances to be unioned. - * - */ - public abstract GeometryCursor execute(GeometryCursor inputGeometries, - SpatialReference sr, ProgressTracker progressTracker); - - /** - *Performs the Topological Union operation on two geometries. - *@param geom1 and geom2 are the geometry instances to be unioned. - * - */ - public abstract Geometry execute(Geometry geom1, Geometry geom2, - SpatialReference sr, ProgressTracker progressTracker); - - public static OperatorUnion local() { - return (OperatorUnion) OperatorFactoryLocal.getInstance().getOperator( - Type.Union); - } + @Override + public Type getType() { + return Type.Union; + } + + /** + * Performs the Topological Union operation on the geometry set. + * + * @param inputGeometries + * is the set of Geometry instances to be unioned. + * + * @param sr + * the spatial reference of the input geometries + * + * @param progressTracker + * the callback used by lengthy operations + * + * @return a cursor for the given input geometries + */ + public abstract GeometryCursor execute(GeometryCursor inputGeometries, + SpatialReference sr, ProgressTracker progressTracker); + + /** + * Performs the Topological Union operation on two geometries. + * + * @param geom1 + * the first geometry of a pair to be unioned. + * + * @param geom1 + * the second geometry of a pair to be unioned. + * + * @return a geometry representing the union of input geometries + */ + public abstract Geometry execute(Geometry geom1, Geometry geom2, + SpatialReference sr, ProgressTracker progressTracker); + + public static OperatorUnion local() { + return (OperatorUnion) OperatorFactoryLocal.getInstance().getOperator( + Type.Union); + } } diff --git a/src/main/java/com/esri/core/geometry/Point.java b/src/main/java/com/esri/core/geometry/Point.java index 0f553257..4a30278a 100644 --- a/src/main/java/com/esri/core/geometry/Point.java +++ b/src/main/java/com/esri/core/geometry/Point.java @@ -94,7 +94,7 @@ public Point(double x, double y, double z) { } /** - * Returns XY coordinates of this point. + * @return a new {@link Point2D} containing XY coordinates of this point. */ public final Point2D getXY() { if (isEmptyImpl()) @@ -108,6 +108,9 @@ public final Point2D getXY() { /** * Returns XY coordinates of this point. + * + * @param pt + * the point to apply XY coordinates to. */ public final void getXY(Point2D pt) { if (isEmptyImpl()) @@ -118,8 +121,10 @@ public final void getXY(Point2D pt) { } /** - * Sets the XY coordinates of this point. param pt The point to create the X - * and Y coordinate from. + * Sets the XY coordinates of this point. + * + * @param pt + * The point to create the X and Y coordinate from. */ public final void setXY(Point2D pt) { _touch(); @@ -127,7 +132,7 @@ public final void setXY(Point2D pt) { } /** - * Returns XYZ coordinates of the point. Z will be set to 0 if Z is missing. + * @return the XYZ coordinates of the point. Z will be set to 0 if Z is missing. */ Point3D getXYZ() { if (isEmptyImpl()) @@ -178,7 +183,7 @@ void setXYZ(Point3D pt) { } /** - * Returns the X coordinate of the point. + * @return the X coordinate of the point. */ public final double getX() { if (isEmptyImpl()) @@ -199,7 +204,7 @@ public void setX(double x) { } /** - * Returns the Y coordinate of this point. + * @return the Y coordinate of this point. */ public final double getY() { if (isEmptyImpl()) @@ -220,7 +225,7 @@ public void setY(double y) { } /** - * Returns the Z coordinate of this point. + * @return the Z coordinate of this point. */ public double getZ() { return getAttributeAsDbl(Semantics.Z, 0); @@ -237,7 +242,7 @@ public void setZ(double z) { } /** - * Returns the attribute M of this point. + * @return the attribute M of this point. */ public double getM() { return getAttributeAsDbl(Semantics.M, 0); @@ -254,7 +259,7 @@ public void setM(double m) { } /** - * Returns the ID of this point. + * @return the ID of this point. */ public int getID() { return getAttributeAsInt(Semantics.ID, 0); diff --git a/src/main/java/com/esri/core/geometry/Point2D.java b/src/main/java/com/esri/core/geometry/Point2D.java index f9fa71ab..4318dc7d 100644 --- a/src/main/java/com/esri/core/geometry/Point2D.java +++ b/src/main/java/com/esri/core/geometry/Point2D.java @@ -153,6 +153,11 @@ public void scale(double f) { /** * Compares two vertices lexicographicaly. + * + * @param other + * The object to compare this {@code String} against + * + * @return 0 if identical TODO */ public int compare(Point2D other) { return y < other.y ? -1 : (y > other.y ? 1 : (x < other.x ? -1 @@ -235,6 +240,9 @@ public void leftPerpendicular() { /** * 90 degree rotation, anticlockwise. Equivalent to RotateDirect(cos(pi/2), * sin(pi/2)). + * + * @param pt + * source point */ public void leftPerpendicular(Point2D pt) { x = -pt.y; @@ -254,6 +262,8 @@ public void rightPerpendicular() { /** * 270 degree rotation, anticlockwise. Equivalent to * RotateDirect(-cos(pi/2), sin(-pi/2)). + * @param pt + * source point */ public void rightPerpendicular(Point2D pt) { x = pt.y; @@ -297,6 +307,8 @@ final int _getQuarter() { * The quarters are numbered counterclockwise. * Angle intervals corresponding to quarters: 1 : [0 : 90); 2 : [90 : 180); * 3 : [180 : 270); 4 : [270 : 360) + * + * @return 1, 2, 3 or 4 corresponding to the quarter of XY plane the vector lies in */ public int getQuarter() { return _getQuarter(); } @@ -333,6 +345,13 @@ final static int _compareVectors(Point2D v1, Point2D v2) { * compareVectors(V1, V2) == -1. * compareVectors(V1, V3) == -1. * compareVectors(V2, V3) == 1. + * + * @param v1 + * first vector under test + * + * @param v2 + * second vector under test + * * @return Returns 1 if v1 is less than v2, 0 if equal, and 1 if greater. */ public static int compareVectors(Point2D v1, Point2D v2) { @@ -415,9 +434,20 @@ public boolean isNaN() { } /** - * Calculates the orientation of the triangle formed by p->q->r. Returns 1 + * Calculates the orientation of the triangle formed by {@literal p->q->r}. Returns 1 * for counter-clockwise, -1 for clockwise, and 0 for collinear. May use * high precision arithmetics for some special degenerate cases. + * + * @param p + * first point of triangle + * + * @param q + * second point of triangle + * + * @param r + * third point of triangle + * + * @return 1 for counter-clockwise, -1 for clockwise, and 0 for collinear. */ public static int orientationRobust(Point2D p, Point2D q, Point2D r) { ECoordinate det_ec = new ECoordinate(); diff --git a/src/main/java/com/esri/core/geometry/Polygon.java b/src/main/java/com/esri/core/geometry/Polygon.java index 6d2a97f4..779d2bd6 100644 --- a/src/main/java/com/esri/core/geometry/Polygon.java +++ b/src/main/java/com/esri/core/geometry/Polygon.java @@ -64,7 +64,7 @@ public Geometry.Type getType() { /** * Calculates the ring area for this ring. - * + * * @param ringIndex * The index of this ring. * @return The ring area for this ring. @@ -74,16 +74,19 @@ public double calculateRingArea2D(int ringIndex) { } /** - * Returns TRUE if the ring is an exterior ring. Valid only for simple - * polygons. + * @param partIndex + * index of the polygon part under test + * + * @return {@code true} if the ring is an exterior ring. Valid only for + * simple polygons. */ public boolean isExteriorRing(int partIndex) { return m_impl.isExteriorRing(partIndex); } /** - * Returns TRUE when this geometry has exactly same type, properties, and - * coordinates as the other geometry. + * @return {@code true} when this geometry has exactly same type, + * properties, and coordinates as the other geometry. */ @Override public boolean equals(Object other) { @@ -110,7 +113,7 @@ public int hashCode() { /** * Sets a new vertex for the polygon. - * + * * @param i * The index of the new vertex. * @param x @@ -138,40 +141,47 @@ public void interpolateAttributes(int semantics, int path_index, public int getExteriorRingCount() { return m_impl.getOGCPolygonCount(); } - - public interface FillRule { - /** - * odd-even fill rule. This is the default value. A point is in the polygon interior if a ray - * from this point to infinity crosses odd number of segments of the polygon. - */ - public final static int enumFillRuleOddEven = 0; - /** + + public interface FillRule { + /** + * odd-even fill rule. This is the default value. A point is in the polygon interior if a ray + * from this point to infinity crosses odd number of segments of the polygon. + */ + public final static int enumFillRuleOddEven = 0; + /** * winding fill rule (aka non-zero winding rule). A point is in the polygon interior if a winding number is not zero. * To compute a winding number for a point, draw a ray from this point to infinity. If N is the number of times the ray * crosses segments directed up and the M is the number of times it crosses segments directed down, - * then the winding number is equal to N-M. + * then the winding number is equal to N-M. */ public final static int enumFillRuleWinding = 1; }; - + /** - *Fill rule for the polygon that defines the interior of the self intersecting polygon. It affects the Simplify operation. - *Can be use by drawing code to pass around the fill rule of graphic path. - *This property is not persisted in any format yet. - *See also Polygon.FillRule. - */ + * Fill rule for the polygon that defines the interior of the self + * intersecting polygon. It affects the Simplify operation. + * Can be use by drawing code to pass around the fill rule of graphic path. + * This property is not persisted in any format yet. + * See also Polygon.FillRule. + * + * @param rule the {@link com.esri.core.geometry.Polygon.FillRule} int value + */ public void setFillRule(int rule) { - m_impl.setFillRule(rule); + m_impl.setFillRule(rule); } - + /** - *Fill rule for the polygon that defines the interior of the self intersecting polygon. It affects the Simplify operation. - *Changing the fill rule on the polygon that has no self intersections has no physical effect. - *Can be use by drawing code to pass around the fill rule of graphic path. - *This property is not persisted in any format yet. - *See also Polygon.FillRule. - */ + * Fill rule for the polygon that defines the interior of the self + * intersecting polygon. It affects the Simplify operation. + * Changing the fill rule on the polygon that has no self intersections + * has no physical effect. + * Can be use by drawing code to pass around the fill rule of graphic path. + * This property is not persisted in any format yet. + * See also Polygon.FillRule. + * + * @return {@link com.esri.core.geometry.Polygon.FillRule} int value + */ public int getFillRule() { - return m_impl.getFillRule(); + return m_impl.getFillRule(); } } diff --git a/src/main/java/com/esri/core/geometry/Polyline.java b/src/main/java/com/esri/core/geometry/Polyline.java index b95e9f81..7fe08cec 100644 --- a/src/main/java/com/esri/core/geometry/Polyline.java +++ b/src/main/java/com/esri/core/geometry/Polyline.java @@ -50,6 +50,12 @@ public Polyline() { /** * Creates a polyline with one line segment. + * + * @param start + * point of the first path + * + * @param end + * point of the first path */ public Polyline(Point start, Point end) { m_impl = new MultiPathImpl(false, start.getDescription()); @@ -73,7 +79,7 @@ public Geometry.Type getType() { } /** - * Returns TRUE when this geometry has exactly same type, properties, and + * @return {@code true} when this geometry has exactly same type, properties, and * coordinates as the other geometry. */ @Override @@ -91,9 +97,8 @@ public boolean equals(Object other) { } /** - * Returns the hash code for the polyline. + * @return the hash code for the polyline. */ - @Override public int hashCode() { return m_impl.hashCode(); diff --git a/src/main/java/com/esri/core/geometry/ProgressTracker.java b/src/main/java/com/esri/core/geometry/ProgressTracker.java index 09933688..091d94c4 100644 --- a/src/main/java/com/esri/core/geometry/ProgressTracker.java +++ b/src/main/java/com/esri/core/geometry/ProgressTracker.java @@ -27,20 +27,29 @@ *A callback to provide progress and cancel tracking mechanism for lengthy operation. */ public abstract class ProgressTracker { - /** - *Periodically called by a lengthy operation to check if the caller requested to cancel. - *@param step The current step of the operation. - *@param totalExpectedSteps is the number of steps the operation is expects to complete its task. - *@return true, if the operation can continue. Returns False, when the operation has to terminate due to a user cancelation. - */ - public abstract boolean progress(int step, int totalExpectedSteps); - - /** - * Checks the tracker and throws UserCancelException if tracker is not null and progress returns false - * @param tracker can be null, then the method does nothing. - */ - public static void checkAndThrow(ProgressTracker tracker) { - if (tracker != null && !tracker.progress(-1, -1)) - throw new UserCancelException(); - } + /** + * Periodically called by a lengthy operation to check if the caller requested to cancel. + * + * @param step + * The current step of the operation. + * + * @param totalExpectedSteps + * is the number of steps the operation is expects to complete its task. + * + * @return {@code true} if the operation can continue. Returns {@code false} + * when the operation has to terminate due to a user cancelation. + */ + public abstract boolean progress(int step, int totalExpectedSteps); + + /** + * Checks the tracker and throws UserCancelException if tracker is not null + * and progress returns false + * + * @param tracker + * can be null, then the method does nothing. + */ + public static void checkAndThrow(ProgressTracker tracker) { + if (tracker != null && !tracker.progress(-1, -1)) + throw new UserCancelException(); + } } diff --git a/src/main/java/com/esri/core/geometry/Proximity2DResult.java b/src/main/java/com/esri/core/geometry/Proximity2DResult.java index 0e1efe71..81d3fd90 100644 --- a/src/main/java/com/esri/core/geometry/Proximity2DResult.java +++ b/src/main/java/com/esri/core/geometry/Proximity2DResult.java @@ -49,7 +49,7 @@ public void setRightSide(boolean bRight) { } /** - * Returns TRUE if the Proximity2DResult is empty. This only happens if the + * @return {@code true} if the Proximity2DResult is empty. This only happens if the * Geometry passed to the Proximity operator is empty. */ public boolean isEmpty() { @@ -57,7 +57,7 @@ public boolean isEmpty() { } /** - * Returns the closest coordinate for + * @return the closest coordinate for * OperatorProximity2D.getNearestCoordinate or the vertex coordinates for * the OperatorProximity2D.getNearestVertex and * OperatorProximity2D.getNearestVertices. @@ -70,7 +70,7 @@ public Point getCoordinate() { } /** - * Returns the vertex index. For OperatorProximity2D.getNearestCoordinate + * @return the vertex index. For OperatorProximity2D.getNearestCoordinate * the behavior is: When the input is a polygon or an envelope and the * bTestPolygonInterior is true, the value is zero. When the input is a * polygon or an Envelope and the bTestPolygonInterior is false, the value @@ -87,7 +87,7 @@ public int getVertexIndex() { } /** - * Returns the distance to the closest vertex or coordinate. + * @return the distance to the closest vertex or coordinate. */ public double getDistance() { if (isEmpty()) @@ -97,7 +97,7 @@ public double getDistance() { } /** - *Returns true if the closest coordinate is to the right of the MultiPath. + * @return {@code true} if the closest coordinate is to the right of the MultiPath. */ public boolean isRightSide() { return (m_info & (int) OperatorProximity2D.ProxResultInfo.rightSide) != 0; diff --git a/src/main/java/com/esri/core/geometry/QuadTree.java b/src/main/java/com/esri/core/geometry/QuadTree.java index 9f6be163..7785f3a3 100644 --- a/src/main/java/com/esri/core/geometry/QuadTree.java +++ b/src/main/java/com/esri/core/geometry/QuadTree.java @@ -31,8 +31,12 @@ public static final class QuadTreeIterator { * Resets the iterator to an starting state on the Quad_tree. If the * input Geometry is a Line segment, then the query will be the segment. * Otherwise the query will be the Envelope_2D bounding the Geometry. - * \param query The Geometry used for the query. \param tolerance The - * tolerance used for the intersection tests. + * + * @param query + * The Geometry used for the query. + * + * @param tolerance + * The tolerance used for the intersection tests. */ public void resetIterator(Geometry query, double tolerance) { m_impl.resetIterator(query, tolerance); @@ -40,24 +44,29 @@ public void resetIterator(Geometry query, double tolerance) { /** * Resets the iterator to a starting state on the Quad_tree using the - * input Envelope_2D as the query. \param query The Envelope_2D used for - * the query. \param tolerance The tolerance used for the intersection - * tests. + * input Envelope_2D as the query. + * + * @param query + * The Envelope_2D used for the query. + * + * @param tolerance + * The tolerance used for the intersection tests. */ public void resetIterator(Envelope2D query, double tolerance) { m_impl.resetIterator(query, tolerance); } /** - * Moves the iterator to the next Element_handle and returns the - * Element_handle. + * Moves the iterator to the next Element_handle + * + * @return the Element_handle. */ public int next() { return m_impl.next(); } /** - * Returns a void* to the impl class. + * @return the implementation object. */ Object getImpl_() { return m_impl; @@ -76,8 +85,13 @@ private QuadTreeIterator(Object obj) { * Creates a Quad_tree with the root having the extent of the input * Envelope_2D, and height of the input height, where the root starts at * height 0. Note that the height cannot be larger than 16 if on a 32 bit - * platform and 32 if on a 64 bit platform. \param extent The extent of the - * Quad_tree. \param height The max height of the Quad_tree. + * platform and 32 if on a 64 bit platform. + * + * @param extent + * The extent of the Quad_tree. + * + * @param height + * The max height of the Quad_tree. */ public QuadTree(Envelope2D extent, int height) { m_impl = new QuadTreeImpl(extent, height); @@ -86,10 +100,15 @@ public QuadTree(Envelope2D extent, int height) { /** * Inserts the element and bounding_box into the Quad_tree. Note that a copy * will me made of the input bounding_box. Note that this will invalidate - * any active iterator on the Quad_tree. Returns an Element_handle - * corresponding to the element and bounding_box. \param element The element - * of the Geometry to be inserted. \param bounding_box The bounding_box of - * the Geometry to be inserted. + * any active iterator on the Quad_tree. + * + * @param element + * The element of the Geometry to be inserted. + * + * @param bounding_box + * The bounding_box of the Geometry to be inserted. + * + * @return an Element_handle corresponding to the element and bounding_box. */ public int insert(int element, Envelope2D bounding_box) { return m_impl.insert(element, bounding_box); @@ -99,12 +118,20 @@ public int insert(int element, Envelope2D bounding_box) { * Inserts the element and bounding_box into the Quad_tree at the given * quad_handle. Note that a copy will me made of the input bounding_box. * Note that this will invalidate any active iterator on the Quad_tree. - * Returns an Element_handle corresponding to the element and bounding_box. - * \param element The element of the Geometry to be inserted. \param - * bounding_box The bounding_box of the Geometry to be inserted. \param - * hint_index A handle used as a hint where to place the element. This can - * be a handle obtained from a previous insertion and is useful on data - * having strong locality such as segments of a Polygon. + * + * @param element + * The element of the Geometry to be inserted. + * + * @param bounding_box + * The bounding_box of the Geometry to be inserted. + * + * @param hint_index + * A handle used as a hint where to place the element. + * This can be a handle obtained from a previous + * insertion and is useful on data having strong + * locality such as segments of a Polygon. + * + * @return an Element_handle corresponding to the element and bounding_box. */ public int insert(int element, Envelope2D bounding_box, int hint_index) { return m_impl.insert(element, bounding_box, hint_index); @@ -112,8 +139,10 @@ public int insert(int element, Envelope2D bounding_box, int hint_index) { /** * Removes the element and bounding_box at the given element_handle. Note - * that this will invalidate any active iterator on the Quad_tree. \param - * element_handle The handle corresponding to the element and bounding_box + * that this will invalidate any active iterator on the Quad_tree. + * + * @param element_handle + * The handle corresponding to the element and bounding_box * to be removed. */ public void removeElement(int element_handle) { @@ -121,39 +150,47 @@ public void removeElement(int element_handle) { } /** - * Returns the element at the given element_handle. \param element_handle - * The handle corresponding to the element to be retrieved. + * @param element_handle + * The handle corresponding to the element to be retrieved. + * + * @return the element at the given element_handle. */ public int getElement(int element_handle) { return m_impl.getElement(element_handle); } /** - * Returns the height of the quad at the given quad_handle. \param - * quad_handle The handle corresponding to the quad. + * @param quad_handle + * The handle corresponding to the quad. + * + * @return the height of the quad at the given quad_handle. */ public int getHeight(int quad_handle) { return m_impl.getHeight(quad_handle); } /** - * Returns the extent of the quad at the given quad_handle. \param - * quad_handle The handle corresponding to the quad. + * @param quad_handle + * The handle corresponding to the quad. + * + * @return the extent of the quad at the given quad_handle. */ public Envelope2D getExtent(int quad_handle) { return m_impl.getExtent(quad_handle); } /** - * Returns the Quad_handle of the quad containing the given element_handle. - * \param element_handle The handle corresponding to the element. + * @param element_handle + * The handle corresponding to the element. + * + * @return the Quad_handle of the quad containing the given element_handle. */ public int getQuad(int element_handle) { return m_impl.getQuad(element_handle); } /** - * Returns the number of elements in the Quad_tree. + * @return the number of elements in the Quad_tree. */ public int getElementCount() { return m_impl.getElementCount(); @@ -163,10 +200,17 @@ public int getElementCount() { * Gets an iterator on the Quad_tree. The query will be the Envelope_2D that * bounds the input Geometry. To reuse the existing iterator on the same * Quad_tree but with a new query, use the reset_iterator function on the - * Quad_tree_iterator. \param query The Geometry used for the query. If the - * Geometry is a Line segment, then the query will be the segment. Otherwise - * the query will be the Envelope_2D bounding the Geometry. \param tolerance - * The tolerance used for the intersection tests. + * Quad_tree_iterator. + * + * @param query + * The Geometry used for the query. If the Geometry is a Line + * segment, then the query will be the segment. Otherwise the + * query will be the Envelope_2D bounding the Geometry. + * + * @param tolerance + * The tolerance used for the intersection tests. + * + * @return iterator on the quad tree for the given input parameters */ public QuadTreeIterator getIterator(Geometry query, double tolerance) { QuadTreeImpl.QuadTreeIteratorImpl iterator = m_impl.getIterator(query, @@ -178,8 +222,15 @@ public QuadTreeIterator getIterator(Geometry query, double tolerance) { * Gets an iterator on the Quad_tree using the input Envelope_2D as the * query. To reuse the existing iterator on the same Quad_tree but with a * new query, use the reset_iterator function on the Quad_tree_iterator. - * \param query The Envelope_2D used for the query. \param tolerance The - * tolerance used for the intersection tests. + * + * @param query + * The Envelope_2D used for the query. + * + * @param tolerance + * The tolerance used for the intersection tests. + * + * @return an iterator on the Quad_tree using the input Envelope_2D as the + * query. */ public QuadTreeIterator getIterator(Envelope2D query, double tolerance) { QuadTreeImpl.QuadTreeIteratorImpl iterator = m_impl.getIterator(query, @@ -188,7 +239,7 @@ public QuadTreeIterator getIterator(Envelope2D query, double tolerance) { } /** - * Gets an iterator on the Quad_tree. + * @return an iterator on the Quad_tree. */ public QuadTreeIterator getIterator() { QuadTreeImpl.QuadTreeIteratorImpl iterator = m_impl.getIterator(); @@ -196,7 +247,7 @@ public QuadTreeIterator getIterator() { } /** - * Returns a void* to the impl class. + * @return the implementation object. */ Object getImpl_() { return m_impl; diff --git a/src/main/java/com/esri/core/geometry/QuadTreeImpl.java b/src/main/java/com/esri/core/geometry/QuadTreeImpl.java index cbef824b..5d3e85f0 100644 --- a/src/main/java/com/esri/core/geometry/QuadTreeImpl.java +++ b/src/main/java/com/esri/core/geometry/QuadTreeImpl.java @@ -31,9 +31,16 @@ static final class QuadTreeIteratorImpl { * Resets the iterator to an starting state on the Quad_tree_impl. If * the input Geometry is a Line segment, then the query will be the * segment. Otherwise the query will be the Envelope_2D bounding the - * Geometry. \param query The Geometry used for the query. \param - * tolerance The tolerance used for the intersection tests. \param - * tolerance The tolerance used for the intersection tests. + * Geometry. + * + * @param query + * The Geometry used for the query. + * + * @param tolerance + * The tolerance used for the intersection tests. + * + * @param tolerance + * The tolerance used for the intersection tests. */ void resetIterator(Geometry query, double tolerance) { m_quads_stack.resize(0); @@ -65,9 +72,12 @@ void resetIterator(Geometry query, double tolerance) { /** * Resets the iterator to a starting state on the Quad_tree_impl using - * the input Envelope_2D as the query. \param query The Envelope_2D used - * for the query. \param tolerance The tolerance used for the - * intersection tests. + * the input Envelope_2D as the query. + * @param query + * The Envelope_2D used for the query. + * + * @param tolerance + * The tolerance used for the intersection tests. */ void resetIterator(Envelope2D query, double tolerance) { m_quads_stack.resize(0); @@ -267,8 +277,13 @@ int next() { * Creates a Quad_tree_impl with the root having the extent of the input * Envelope_2D, and height of the input height, where the root starts at * height 0. Note that the height cannot be larger than 16 if on a 32 bit - * platform and 32 if on a 64 bit platform. \param extent The extent of the - * Quad_tree_impl. \param height The max height of the Quad_tree_impl. + * platform and 32 if on a 64 bit platform. + * + * @param extent + * The extent of the Quad_tree_impl. + * + * @param height + * The max height of the Quad_tree_impl. */ QuadTreeImpl(Envelope2D extent, int height) { m_quad_tree_nodes = new StridedIndexTypeCollection(11); @@ -280,9 +295,13 @@ int next() { } /** - * Resets the Quad_tree_impl to the given extent and height. \param extent - * The extent of the Quad_tree_impl. \param height The max height of the - * Quad_tree_impl. + * Resets the Quad_tree_impl to the given extent and height. + * + * @param extent + * The extent of the Quad_tree_impl. + * + * @param height + * The max height of the Quad_tree_impl. */ void reset(Envelope2D extent, int height) { m_quad_tree_nodes.deleteAll(false); @@ -295,9 +314,13 @@ void reset(Envelope2D extent, int height) { /** * Inserts the element and bounding_box into the Quad_tree_impl. Note that * this will invalidate any active iterator on the Quad_tree_impl. Returns - * an int corresponding to the element and bounding_box. \param element The - * element of the Geometry to be inserted. \param bounding_box The - * bounding_box of the Geometry to be inserted. + * an int corresponding to the element and bounding_box. + * + * @param element + * The element of the Geometry to be inserted. + * + * @param bounding_box + * The bounding_box of the Geometry to be inserted. */ int insert(int element, Envelope2D bounding_box) { return insert_(element, bounding_box, 0, m_extent, m_root, false, -1); @@ -306,12 +329,21 @@ int insert(int element, Envelope2D bounding_box) { /** * Inserts the element and bounding_box into the Quad_tree_impl at the given * quad_handle. Note that this will invalidate any active iterator on the - * Quad_tree_impl. Returns an int corresponding to the element and - * bounding_box. \param element The element of the Geometry to be inserted. - * \param bounding_box The bounding_box of the Geometry to be inserted. - * \param hint_index A handle used as a hint where to place the element. - * This can be a handle obtained from a previous insertion and is useful on - * data having strong locality such as segments of a Polygon. + * Quad_tree_impl. + * + * @param element + * The element of the Geometry to be inserted. + * + * @param bounding_box + * The bounding_box of the Geometry to be inserted. + * + * @param hint_index + * A handle used as a hint where to place the element. + * This can be a handle obtained from a previous insertion and is + * useful on data having strong locality such as segments of a + * Polygon. + * + * @return an int corresponding to the element and bounding_box. */ int insert(int element, Envelope2D bounding_box, int hint_index) { int quad_handle; @@ -330,8 +362,10 @@ int insert(int element, Envelope2D bounding_box, int hint_index) { /** * Removes the element and bounding_box at the given element_handle. Note * that this will invalidate any active iterator on the Quad_tree_impl. - * \param element_handle The handle corresponding to the element and - * bounding_box to be removed. + * + * @param element_handle + * The handle corresponding to the element and bounding_box to be + * removed. */ void removeElement(int element_handle) { int quad_handle = getQuad_(element_handle); @@ -345,37 +379,43 @@ void removeElement(int element_handle) { } /** - * Returns the element at the given element_handle. - * \param element_handle - * The handle corresponding to the element to be retrieved. + * @param element_handle + * The handle corresponding to the element to be retrieved. + * + * @return the element at the given element_handle. */ int getElement(int element_handle) { return getElement_(element_handle); } - /** - * Returns a reference to the element extent at the given element_handle. - * \param element_handle - * The handle corresponding to the element to be retrieved. - */ - Envelope2D getElementExtent(int element_handle) - { - int box_handle = getBoxHandle_(element_handle); - return getBoundingBox_(box_handle); - } + /** + * Returns a reference to the element extent at the given element_handle. + * + * @param element_handle + * The handle corresponding to the element to be retrieved. + */ + Envelope2D getElementExtent(int element_handle) + { + int box_handle = getBoxHandle_(element_handle); + return getBoundingBox_(box_handle); + } /** - * Returns the height of the quad at the given quad_handle. \param - * quad_handle The handle corresponding to the quad. + * @param quad_handle + * The handle corresponding to the quad. + * + * @return the height of the quad at the given quad_handle. */ int getHeight(int quad_handle) { return getHeight_(quad_handle); } /** - * Returns the extent of the quad at the given quad_handle. \param - * quad_handle The handle corresponding to the quad. + * @param quad_handle + * The handle corresponding to the quad. + * + * @return the extent of the quad at the given quad_handle. */ Envelope2D getExtent(int quad_handle) { Envelope2D quad_extent = new Envelope2D(); @@ -407,23 +447,28 @@ Envelope2D getExtent(int quad_handle) { } /** - * Returns the int of the quad containing the given element_handle. \param - * element_handle The handle corresponding to the element. + * @param element_handle + * The handle corresponding to the element. + * + * @return the int of the quad containing the given element_handle. */ int getQuad(int element_handle) { return getQuad_(element_handle); } /** - * Returns the number of elements in the Quad_tree_impl. + * @return the number of elements in the Quad_tree_impl. */ int getElementCount() { return getSubTreeElementCount_(m_root); } /** - * Returns the number of elements in the subtree rooted at the given - * quad_handle. \param quad_handle The handle corresponding to the quad. + * @param quad_handle + * The handle corresponding to the quad. + * + * @return the number of elements in the subtree rooted at the given + * quad_handle. */ int getSubTreeElementCount(int quad_handle) { return getSubTreeElementCount_(quad_handle); @@ -433,10 +478,15 @@ int getSubTreeElementCount(int quad_handle) { * Gets an iterator on the Quad_tree_impl. The query will be the Envelope_2D * that bounds the input Geometry. To reuse the existing iterator on the * same Quad_tree_impl but with a new query, use the reset_iterator function - * on the Quad_tree_iterator_impl. \param query The Geometry used for the - * query. If the Geometry is a Line segment, then the query will be the - * segment. Otherwise the query will be the Envelope_2D bounding the - * Geometry. \param tolerance The tolerance used for the intersection tests. + * on the Quad_tree_iterator_impl. + * + * @param query + * The Geometry used for the query. If the Geometry is a Line + * segment, then the query will be the segment. Otherwise the + * query will be the Envelope_2D bounding the Geometry. + * + * @param tolerance + * The tolerance used for the intersection tests. */ QuadTreeIteratorImpl getIterator(Geometry query, double tolerance) { return new QuadTreeIteratorImpl(this, query, tolerance); @@ -446,15 +496,23 @@ QuadTreeIteratorImpl getIterator(Geometry query, double tolerance) { * Gets an iterator on the Quad_tree_impl using the input Envelope_2D as the * query. To reuse the existing iterator on the same Quad_tree_impl but with * a new query, use the reset_iterator function on the - * Quad_tree_iterator_impl. \param query The Envelope_2D used for the query. - * \param tolerance The tolerance used for the intersection tests. + * Quad_tree_iterator_impl. + * + * @param query + * The Envelope_2D used for the query. + * + * @param tolerance + * The tolerance used for the intersection tests. + * + * @return an iterator on the Quad_tree_impl using the input Envelope_2D as + * the query */ QuadTreeIteratorImpl getIterator(Envelope2D query, double tolerance) { return new QuadTreeIteratorImpl(this, query, tolerance); } /** - * Gets an iterator on the Quad_tree. + * @return an iterator on the Quad_tree. */ QuadTreeIteratorImpl getIterator() { return new QuadTreeIteratorImpl(this); diff --git a/src/main/java/com/esri/core/geometry/RasterizedGeometry2D.java b/src/main/java/com/esri/core/geometry/RasterizedGeometry2D.java index 46ccd5c6..d80a3864 100644 --- a/src/main/java/com/esri/core/geometry/RasterizedGeometry2D.java +++ b/src/main/java/com/esri/core/geometry/RasterizedGeometry2D.java @@ -42,11 +42,26 @@ private HitType(int val) { /** * Test a point against the RasterizedGeometry + * + * @param x + * the X coordinate of the position under test + * + * @param y + * the Y coordinate of the position under test + * + * @return the HitType signifying if the geometry is inside, outside or on + * the border */ public abstract HitType queryPointInGeometry(double x, double y); /** * Test an envelope against the RasterizedGeometry. + * + * @param env + * the envelope under test + * + * @return the HitType signifying if the geometry is inside, outside or on + * the border */ public abstract HitType queryEnvelopeInGeometry(Envelope2D env); @@ -54,16 +69,20 @@ private HitType(int val) { * Creates a rasterized geometry from a given Geometry. * * @param geom - * The input geometry to rasterize. It has to be a MultiVertexGeometry instance. + * The input geometry to rasterize. It has to be a MultiVertexGeometry instance. + * * @param toleranceXY - * The tolerance of the rasterization. Raster pixels that are - * closer than given tolerance to the Geometry will be set. - * @param rasterSizeBytes - * The max size of the raster in bytes. The raster has size of - * rasterSize x rasterSize. Polygons are rasterized into 2 bpp - * (bits per pixel) rasters while other geometries are rasterized - * into 1 bpp rasters. 32x32 pixel raster for a polygon would - * take 256 bytes of memory + * The tolerance of the rasterization. Raster pixels that are + * closer than given tolerance to the Geometry will be set. + * + * @param rasterSizeBytes + * The max size of the raster in bytes. The raster has size of + * rasterSize x rasterSize. Polygons are rasterized into 2 bpp + * (bits per pixel) rasters while other geometries are rasterized + * into 1 bpp rasters. 32x32 pixel raster for a polygon would + * take 256 bytes of memory + * + * @return a rasterized geometry from a given Geometry. */ public static RasterizedGeometry2D create(Geometry geom, double toleranceXY, int rasterSizeBytes) { @@ -109,6 +128,8 @@ public static int rasterSizeFromAccelerationDegree( /** * Checks whether the RasterizedGeometry2D accelerator can be used with the * given geometry. + * + * @return {@code true} if the geometry can use the accelerator */ static boolean canUseAccelerator(Geometry geom) { if (geom.isEmpty() @@ -119,20 +140,22 @@ static boolean canUseAccelerator(Geometry geom) { } /** - * Returns the tolerance for which the rasterized Geometry has been built. + * @return the tolerance for which the rasterized Geometry has been built. */ public abstract double getToleranceXY(); /** - * Returns raster size in bytes + * @return raster size in bytes */ public abstract int getRasterSize(); /** * Dumps the raster to a bmp file for debug purposes. * - * @param fileName - * @return true if success, false otherwise. + * @param fileName + * to save debug bitmap file + * + * @return {@code true} if success, false otherwise. */ public abstract boolean dbgSaveToBitmap(String fileName); diff --git a/src/main/java/com/esri/core/geometry/Segment.java b/src/main/java/com/esri/core/geometry/Segment.java index be94b723..a6e6d131 100644 --- a/src/main/java/com/esri/core/geometry/Segment.java +++ b/src/main/java/com/esri/core/geometry/Segment.java @@ -89,6 +89,9 @@ void setStartXYZ(double x, double y, double z) { /** * Returns coordinates of the start point in a Point class. + * + * @param dstPoint + * the Point to populate with segment start point values */ public void queryStart(Point dstPoint) { _get(0, dstPoint); @@ -97,8 +100,8 @@ public void queryStart(Point dstPoint) { /** * Sets the coordinates of the start point in this segment. * - * @param srcPoint - * The new start point of this segment. + * @param srcPoint + * The new start point of this segment. */ public void setStart(Point srcPoint) { _set(0, srcPoint); @@ -108,11 +111,13 @@ public void setStart(Point srcPoint) { * Returns value of the start vertex attribute's ordinate. Throws if the * Point is empty. * - * @param semantics - * The attribute semantics. - * @param ordinate - * The attribute's ordinate. For example, the y coordinate of the - * NORMAL has ordinate of 1. + * @param semantics + * The attribute semantics. + * + * @param ordinate + * The attribute's ordinate. For example, the y coordinate of the + * NORMAL has ordinate of 1. + * * @return Ordinate value as double. */ public double getStartAttributeAsDbl(int semantics, int ordinate) { @@ -123,11 +128,13 @@ public double getStartAttributeAsDbl(int semantics, int ordinate) { * Returns the value of the start vertex attribute's ordinate. The ordinate * is always 0 because integer attributes always have one component. * - * @param semantics - * The attribute semantics. - * @param ordinate - * The attribute's ordinate. For example, the y coordinate of the - * NORMAL has ordinate of 1. + * @param semantics + * The attribute semantics. + * + * @param ordinate + * The attribute's ordinate. For example, the y coordinate of the + * NORMAL has ordinate of 1. + * * @return Ordinate value truncated to 32 bit integer. */ public int getStartAttributeAsInt(int semantics, int ordinate) { @@ -137,12 +144,16 @@ public int getStartAttributeAsInt(int semantics, int ordinate) { /** * Sets the value of the start vertex attribute. * - * @param semantics - * The attribute semantics. - * @param value - * is the array to write values to. The attribute type and the - * number of elements must match the persistence type, as well as - * the number of components of the attribute. + * @param semantics + * The attribute semantics. + * + * @param ordinate + * The attribute's ordinate. + * + * @param value + * is the array to write values to. The attribute type and the + * number of elements must match the persistence type, as well as + * the number of components of the attribute. */ public void setStartAttribute(int semantics, int ordinate, double value) { _setAttribute(0, semantics, ordinate, value); @@ -153,8 +164,6 @@ public void setStartAttribute(int semantics, int ordinate, int value) { } /** - * Returns the X coordinate of starting point. - * * @return The X coordinate of starting point. */ public double getStartX() { @@ -162,8 +171,6 @@ public double getStartX() { } /** - * Returns the Y coordinate of starting point. - * * @return The Y coordinate of starting point. */ public double getStartY() { @@ -171,8 +178,6 @@ public double getStartY() { } /** - * Returns the X coordinate of ending point. - * * @return The X coordinate of ending point. */ public double getEndX() { @@ -180,8 +185,6 @@ public double getEndX() { } /** - * Returns the Y coordinate of ending point. - * * @return The Y coordinate of ending point. */ public double getEndY() { @@ -189,8 +192,6 @@ public double getEndY() { } /** - * Returns XY coordinates of the end point. - * * @return The XY coordinates of the end point. */ Point2D getEndXY() { @@ -205,8 +206,8 @@ void getEndXY(Point2D pt) { /** * Sets the XY coordinates of the end point. * - * @param pt - * The end point of the segment. + * @param pt + * The end point of the segment. */ void setEndXY(Point2D pt) { _setXY(1, pt); @@ -239,8 +240,8 @@ void setEndXYZ(double x, double y, double z) { /** * Returns coordinates of the end point in this segment. * - * @param dstPoint - * The end point of this segment. + * @param dstPoint + * The end point of this segment. */ public void queryEnd(Point dstPoint) { _get(1, dstPoint); @@ -249,8 +250,8 @@ public void queryEnd(Point dstPoint) { /** * Sets the coordinates of the end point in a Point class. * - * @param srcPoint - * The new end point of this segment. + * @param srcPoint + * The new end point of this segment. */ public void setEnd(Point srcPoint) { _set(1, srcPoint); @@ -260,11 +261,13 @@ public void setEnd(Point srcPoint) { * Returns value of the end vertex attribute's ordinate. Throws if the Point * is empty. * - * @param semantics - * The attribute semantics. - * @param ordinate - * The attribute's ordinate. For example, the y coordinate of the - * NORMAL has ordinate of 1. + * @param semantics + * The attribute semantics. + * + * @param ordinate + * The attribute's ordinate. For example, the y coordinate of the + * NORMAL has ordinate of 1. + * * @return Ordinate value as double. */ public double getEndAttributeAsDbl(int semantics, int ordinate) { @@ -275,11 +278,13 @@ public double getEndAttributeAsDbl(int semantics, int ordinate) { * Returns the value of the end vertex attribute's ordinate. The ordinate is * always 0 because integer attributes always have one component. * - * @param semantics - * The attribute semantics. - * @param ordinate - * The attribute's ordinate. For example, the y coordinate of the - * NORMAL has ordinate of 1. + * @param semantics + * The attribute semantics. + * + * @param ordinate + * The attribute's ordinate. For example, the y coordinate of the + * NORMAL has ordinate of 1. + * * @return The ordinate value truncated to 32 bit integer. */ public int getEndAttributeAsInt(int semantics, int ordinate) { @@ -289,14 +294,16 @@ public int getEndAttributeAsInt(int semantics, int ordinate) { /** * Sets the value of end vertex attribute. * - * @param semantics - * The attribute semantics. - * @param ordinate - * The attribute's ordinate. - * @param value - * Is the array to write values to. The attribute type and the - * number of elements must match the persistence type, as well as - * the number of components of the attribute. + * @param semantics + * The attribute semantics. + * + * @param ordinate + * The attribute's ordinate. + * + * @param value + * Is the array to write values to. The attribute type and the + * number of elements must match the persistence type, as well as + * the number of components of the attribute. */ public void setEndAttribute(int semantics, int ordinate, double value) { _setAttribute(1, semantics, ordinate, value); @@ -332,21 +339,26 @@ public double calculateArea2D() { * Note: This is not a topological operation. It needs to be paired with the * Segment.Overlap call. * - * @param other - * The segment to calculate intersection with. - * @param intersectionPoints - * The intersection points. Can be NULL. - * @param paramThis - * The value of the parameter in the intersection points for this - * Segment (between 0 and 1). Can be NULL. - * @param paramOther - * The value of the parameter in the intersection points for the - * other Segment (between 0 and 1). Can be NULL. - * @param tolerance - * The tolerance value for the intersection calculation. Can be - * 0. + * @param other + * The segment to calculate intersection with. + * + * @param intersectionPoints + * The intersection points. Can be NULL. + * + * @param paramThis + * The value of the parameter in the intersection points for this + * Segment (between 0 and 1). Can be NULL. + * + * @param paramOther + * The value of the parameter in the intersection points for the + * other Segment (between 0 and 1). Can be NULL. + * + * @param tolerance + * The tolerance value for the intersection calculation. Can be + * 0. + * * @return The number of intersection points, 0 when no intersection points - * exist. + * exist. */ int intersect(Segment other, Point2D[] intersectionPoints, double[] paramThis, double[] paramOther, double tolerance) { @@ -355,16 +367,16 @@ int intersect(Segment other, Point2D[] intersectionPoints, } /** - * Returns TRUE if this segment intersects with the other segment with the - * given tolerance. + * @return {@code true} if this segment intersects with the other segment + * with the given tolerance. */ boolean isIntersecting(Segment other, double tolerance) { return _isIntersecting(other, tolerance, false) != 0; } /** - * Returns TRUE if the point and segment intersect (not disjoint) for the - * given tolerance. + * @return {@code true} if the point and segment intersect (not disjoint) + * for the given tolerance. */ boolean isIntersecting(Point2D pt, double tolerance) { return _isIntersectingPoint(pt, tolerance, false); @@ -372,6 +384,8 @@ boolean isIntersecting(Point2D pt, double tolerance) { /** * Non public abstract version of the function. + * + * @return always false */ public boolean isEmptyImpl() { return false; @@ -795,23 +809,26 @@ Point2D getCoord2D(double t) { * Returns the coordinate of the point on this segment for the given * parameter value (segments are parametric curves). * - * @param t - * the parameter coordinate along the segment from 0.0 to 1.0. - * Value of 0 returns the start point, 1 returns end point. - * @param dst - * the coordinate where result will be placed. + * @param t + * the parameter coordinate along the segment from 0.0 to 1.0. + * Value of 0 returns the start point, 1 returns end point. + * + * @param dst + * the coordinate where result will be placed. */ abstract void getCoord2D(double t, Point2D dst); /** * Finds a closest coordinate on this segment. * - * @param inputPoint - * The 2D point to find the closest coordinate on this segment. - * @param bExtrapolate - * TRUE if the segment is extrapolated at the end points along - * the end point tangents. Otherwise the result is limited to - * values between 0 and 1. + * @param inputPoint + * The 2D point to find the closest coordinate on this segment. + * + * @param bExtrapolate + * TRUE if the segment is extrapolated at the end points along + * the end point tangents. Otherwise the result is limited to + * values between 0 and 1. + * * @return The parametric coordinate t on the segment (0 corresponds to the * start point, 1 corresponds to the end point). Use getCoord2D to * obtain the 2D coordinate on the segment from t. To find the @@ -824,10 +841,11 @@ abstract double getClosestCoordinate(Point2D inputPoint, * Splits this segment into Y monotonic parts and places them into the input * array. * - * @param monotonicSegments - * The in/out array of SegmentBuffer structures that will be - * filled with the monotonic parts. The monotonicSegments array - * must contain at least 3 elements. + * @param monotonicSegments + * The in/out array of SegmentBuffer structures that will be + * filled with the monotonic parts. The monotonicSegments array + * must contain at least 3 elements. + * * @return The number of monotonic parts if the split had happened. Returns * 0 if the segment is already monotonic. */ @@ -837,18 +855,22 @@ abstract double getClosestCoordinate(Point2D inputPoint, * Calculates intersection points of this segment with an infinite line, * parallel to one of the axes. * - * @param bAxisX - * TRUE if the function works with the line parallel to the axis - * X. - * @param ordinate - * The ordinate value of the line (x for axis Y, y for axis X). - * @param resultOrdinates - * The value of ordinate in the intersection points One ordinate - * is equal to the ordinate parameter. This parameter can be - * NULL. - * @param parameters - * The value of the parameter in the intersection points (between - * 0 and 1). This parameter can be NULL. + * @param bAxisX + * TRUE if the function works with the line parallel to the axis + * X. + * + * @param ordinate + * The ordinate value of the line (x for axis Y, y for axis X). + * + * @param resultOrdinates + * The value of ordinate in the intersection points One ordinate + * is equal to the ordinate parameter. This parameter can be + * NULL. + * + * @param parameters + * The value of the parameter in the intersection points (between + * 0 and 1). This parameter can be NULL. + * * @return The number of intersection points, 0 when no intersection points * exist, -1 when the segment coincides with the line (infinite * number of intersection points). @@ -899,6 +921,19 @@ void _reverseImpl() { /** * Returns the attribute on the segment for the given parameter value. The * interpolation of attribute is given by the attribute interpolation type. + * + * @param t + * TODO + * + * @param semantics + * The attribute semantics. + * + * @param ordinate + * The attribute's ordinate. For example, the y coordinate of the + * NORMAL has ordinate of 1. + * + * @return the attribute on the segment for the given parameter value. + * */ public abstract double getAttributeAsDbl(double t, int semantics, int ordinate); @@ -911,11 +946,13 @@ abstract boolean _isIntersectingPoint(Point2D pt, double tolerance, * parallel to axis X. This segment must be to be y-monotonic (or * horizontal). * - * @param y - * The y coordinate of the line. - * @param xParallel - * For segments, that are horizontal, and have y coordinate, this - * value is returned. + * @param y + * The y coordinate of the line. + * + * @param xParallel + * For segments, that are horizontal, and have y coordinate, this + * value is returned. + * * @return X coordinate of the intersection, or NaN, if no intersection. */ abstract double intersectionOfYMonotonicWithAxisX(double y, double xParallel); diff --git a/src/main/java/com/esri/core/geometry/SegmentIterator.java b/src/main/java/com/esri/core/geometry/SegmentIterator.java index 8312e028..4c1452c5 100644 --- a/src/main/java/com/esri/core/geometry/SegmentIterator.java +++ b/src/main/java/com/esri/core/geometry/SegmentIterator.java @@ -37,7 +37,7 @@ public class SegmentIterator { /** * Moves the iterator to the next path. Returns the TRUE if successful. * - * @return TRUE if the next path exists. + * @return {@code true} if the next path exists. */ public boolean nextPath() { return m_impl.nextPath(); @@ -46,7 +46,7 @@ public boolean nextPath() { /** * Moves the iterator to the previous path. Returns the TRUE if successful. * - * @return TRUE if the previous path exists. + * @return {@code true} if the previous path exists. */ public boolean previousPath() { return m_impl.previousPath(); @@ -72,6 +72,9 @@ public void resetToLastPath() { * Resets the iterator such that a subsequent call to NextPath will set the * iterator to the given path index. A call to PreviousPath will set the * iterator to the path at pathIndex - 1. + * @param pathIndex + * where a subsequent call to {@link SegmentIterator#nextPath()} + * will set the iterator to the given index */ public void resetToPath(int pathIndex) { m_impl.resetToPath(pathIndex); @@ -81,8 +84,8 @@ public void resetToPath(int pathIndex) { * Indicates whether the iterator points to the first segment in the current * path. * - * @return TRUE if the iterator points to the first segment in the current - * path. + * @return {@code true} if the iterator points to the first segment in the + * current path. */ public boolean isFirstSegmentInPath() { return m_impl.isFirstSegmentInPath(); @@ -92,8 +95,8 @@ public boolean isFirstSegmentInPath() { * Indicates whether the iterator points to the last segment in the current * path. * - * @return TRUE if the iterator points to the last segment in the current - * path. + * @return {@code true} if the iterator points to the last segment in the + * current path. */ public boolean isLastSegmentInPath() { return m_impl.isLastSegmentInPath(); @@ -116,12 +119,16 @@ public void resetToLastSegment() { } /** - *Resets the iterator to a specific vertex. - *The call to next_segment will return the segment that starts at the vertex. - *Call to previous_segment will return the segment that starts at the previous vertex. - *@param vertexIndex The vertex index to reset the iterator to. - *@param pathIndex The path index to reset the iterator to. Used as a hint. If the path_index is wrong or -1, then the path_index is automatically calculated. + * Resets the iterator to a specific vertex. + * The call to next_segment will return the segment that starts at the vertex. + * Call to previous_segment will return the segment that starts at the previous vertex. + * @param vertexIndex + * The vertex index to reset the iterator to. * + * @param pathIndex + * The path index to reset the iterator to. Used as a hint. If the + * path_index is wrong or -1, then the path_index is automatically + * calculated. */ public void resetToVertex(int vertexIndex, int pathIndex) { m_impl.resetToVertex(vertexIndex, pathIndex); @@ -130,7 +137,7 @@ public void resetToVertex(int vertexIndex, int pathIndex) { /** * Indicates whether a next segment exists for the path. * - * @return TRUE is the next segment exists. + * @return {@code true} if the next segment exists. */ public boolean hasNextSegment() { return m_impl.hasNextSegment(); @@ -139,7 +146,7 @@ public boolean hasNextSegment() { /** * Indicates whether a previous segment exists in the path. * - * @return TRUE if the previous segment exists. + * @return {@code true} if the previous segment exists. */ public boolean hasPreviousSegment() { return m_impl.hasPreviousSegment(); @@ -149,6 +156,8 @@ public boolean hasPreviousSegment() { * Moves the iterator to the next segment and returns the segment. * * The Segment is returned by value and is owned by the iterator. + * + * @return the next segment */ public Segment nextSegment() { return m_impl.nextSegment(); @@ -158,34 +167,37 @@ public Segment nextSegment() { * Moves the iterator to previous segment and returns the segment. * * The Segment is returned by value and is owned by the iterator. + * + * @return the previous segment */ public Segment previousSegment() { return m_impl.previousSegment(); } /** - * Returns the index of the current path. + * @return the index of the current path. */ public int getPathIndex() { return m_impl.getPathIndex(); } /** - * Returns the index of the start point of this segment. + * @return the index of the start point of this segment. */ public int getStartPointIndex() { return m_impl.getStartPointIndex(); } /** - * Returns the index of the end point of the current segment. + * @return the index of the end point of the current segment. */ public int getEndPointIndex() { return m_impl.getEndPointIndex(); } /** - * Returns TRUE, if the segment is the closing segment of the closed path + * @return {@code true} if the segment is the closing segment of the closed + * path */ public boolean isClosingSegment() { return m_impl.isClosingSegment(); diff --git a/src/main/java/com/esri/core/geometry/SimpleRasterizer.java b/src/main/java/com/esri/core/geometry/SimpleRasterizer.java index 783b8a8f..3f102d1d 100644 --- a/src/main/java/com/esri/core/geometry/SimpleRasterizer.java +++ b/src/main/java/com/esri/core/geometry/SimpleRasterizer.java @@ -62,6 +62,15 @@ public SimpleRasterizer() { /** * Sets up the rasterizer. + * + * @param height + * of raster TODO + * + * @param width + * of raster TODO + * + * @param callback + * executed for each scan of raster data */ public void setup(int width, int height, ScanCallback callback) { @@ -96,6 +105,24 @@ public final void flush() { /** * Adds edges of a triangle. + * + * @param x1 + * first coordinate X value + * + * @param y1 + * first coordinate Y value + * + * @param x2 + * second coordinate X value + * + * @param y2 + * second coordinate Y value + * + * @param x3 + * third coordinate X value + * + * @param y3 + * third coordinate Y value */ public final void addTriangle(double x1, double y1, double x2, double y2, double x3, double y3) { addEdge(x1, y1, x2, y2); @@ -170,11 +197,19 @@ public final void renderEdges(int fillMode) { } /** - * Add a single edge. - * @param x1 - * @param y1 - * @param x2 - * @param y2 + * Add a single edge. + * + * @param x1 + * first coordinate X value + * + * @param y1 + * first coordinate Y value + * + * @param x2 + * second coordinate X value + * + * @param y2 + * second coordinate X value */ public final void addEdge(double x1, double y1, double x2, double y2) { if (y1 == y2) diff --git a/src/main/java/com/esri/core/geometry/Transformation2D.java b/src/main/java/com/esri/core/geometry/Transformation2D.java index f5d07a54..6f6290bf 100644 --- a/src/main/java/com/esri/core/geometry/Transformation2D.java +++ b/src/main/java/com/esri/core/geometry/Transformation2D.java @@ -126,7 +126,7 @@ public boolean equals(Object other) { } /** - * Returns the hash code for the 2D transformation. + * @return the hash code for the 2D transformation. */ @Override @@ -150,13 +150,15 @@ void transform(Point2D[] points, int start, int count) { /** * Transforms an array of points. * - * @param pointsIn - * The points to be transformed. - * @param count - * The number of points to transform. - * @param pointsOut - * The transformed points are returned using this array. It - * should have the same or greater size as the input array. + * @param pointsIn + * The points to be transformed. + * + * @param count + * The number of points to transform. + * + * @param pointsOut + * The transformed points are returned using this array. It should + * have the same or greater size as the input array. */ public void transform(Point[] pointsIn, int count, Point[] pointsOut) { Point2D res = new Point2D(); @@ -172,15 +174,17 @@ public void transform(Point[] pointsIn, int count, Point[] pointsOut) { * Transforms an array of points stored in an array of doubles as * interleaved XY coordinates. * - * @param pointsXYInterleaved - * The array of points with interleaved X, Y values to be - * transformed. - * @param start - * The start point index to transform from (the actual element - * index is 2 * start). - * @param count - * The number of points to transform (the actual element count is - * 2 * count). + * @param pointsXYInterleaved + * The array of points with interleaved X, Y values to be + * transformed. + * + * @param start + * The start point index to transform from (the actual element + * index is 2 * start). + * + * @param count + * The number of points to transform (the actual element count + * is 2 * count). */ public void transform(double[] pointsXYInterleaved, int start, int count) { int n = Math.min(pointsXYInterleaved.length, (start + count) * 2) / 2; @@ -197,8 +201,8 @@ public void transform(double[] pointsXYInterleaved, int start, int count) { * result into this matrix and returns a reference to it.
* Equivalent to this *= right. * - * @param right - * The matrix to be multiplied with. + * @param right + * The matrix to be multiplied with. */ public void multiply(Transformation2D right) { multiply(this, right, this); @@ -209,8 +213,8 @@ public void multiply(Transformation2D right) { * result into this matrix and returns a reference to it.
* Equivalent to this = left * this. * - * @param left - * The matrix to be multiplied with. + * @param left + * The matrix to be multiplied with. */ public void mulLeft(Transformation2D left) { multiply(left, this, this); @@ -221,12 +225,14 @@ public void mulLeft(Transformation2D left) { * this matrix. The a, b, and result could point to same objects.
* Equivalent to result = a * b. * - * @param a - * The 2D transformation to be multiplied. - * @param b - * The 2D transformation to be multiplied. - * @param result - * The 2D transformation created by multiplication of matrices. + * @param a + * The 2D transformation to be multiplied. + * + * @param b + * The 2D transformation to be multiplied. + * + * @param result + * The 2D transformation created by multiplication of matrices. */ public static void multiply(Transformation2D a, Transformation2D b, Transformation2D result) { @@ -248,9 +254,7 @@ public static void multiply(Transformation2D a, Transformation2D b, } /** - * Returns a copy of the Transformation2D object. - * - * @return A copy of this object. + * @return a copy of this Transformation2D object. */ public Transformation2D copy() { Transformation2D result = new Transformation2D(); @@ -267,9 +271,9 @@ public Transformation2D copy() { * Writes the matrix coefficients in the order XX, XY, XD, YX, YY, YD into * the given array. * - * @param coefs - * The array into which the coefficients are returned. Should be - * of size 6 elements. + * @param coefs + * The array into which the coefficients are returned. Should be of + * size 6 elements. */ public void getCoefficients(double[] coefs) { if (coefs.length < 6) @@ -287,8 +291,8 @@ public void getCoefficients(double[] coefs) { /** * Transforms envelope * - * @param env - * The envelope that is to be transformed + * @param env + * The envelope that is to be transformed */ void transform(Envelope2D env) { @@ -384,8 +388,10 @@ Point2D transformSize(Point2D SizeSrc) { /** * Transforms a tolerance value. * - * @param tolerance - * The tolerance value. + * @param tolerance + * The tolerance value. + * + * @return TODO */ public double transform(double tolerance) { // the function should be implemented as follows: find encompassing @@ -441,7 +447,7 @@ public void setIdentity() { } /** - * Returns TRUE if this matrix is the identity matrix. + * @return {@code true} if this matrix is the identity matrix. */ public boolean isIdentity() { return xx == 1.0 && yy == 1.0 @@ -449,11 +455,11 @@ public boolean isIdentity() { } /** - * Returns TRUE if this matrix is an identity matrix within the given - * tolerance. - * - * @param tol - * The tolerance value. + * @param tol + * The tolerance value. + * + * @return true if this matrix is an identity matrix within the given + * tolerance. */ public boolean isIdentity(double tol) { Point2D pt = Point2D.construct(0., 1.); @@ -474,7 +480,7 @@ public boolean isIdentity(double tol) { } /** - * Returns TRUE for reflective transformations. It inverts the sign of + * @return {@code true} for reflective transformations. It inverts the sign of * vector cross product. */ public boolean isReflective() { @@ -482,10 +488,13 @@ public boolean isReflective() { } /** - * Returns TRUE if this transformation is a uniform transformation. - * * The uniform transformation is a transformation, which transforms a square * to a square. + * + * @param eps + * TODO + * + * @return {@code true} if this transformation is a uniform transformation. */ public boolean isUniform(double eps) { double v1 = xx * xx + yx * yx; @@ -495,19 +504,19 @@ public boolean isUniform(double eps) { } /** - * Returns TRUE if this transformation is a shift transformation. The shift - * transformation performs shift only. + * @return {@code true} if this transformation is a shift transformation. + * The shift transformation performs shift only. */ public boolean isShift() { return xx == 1.0 && yy == 1.0 && 0 == xy && 0 == yx; } /** - * Returns TRUE if this transformation is a shift transformation within the - * given tolerance. - * - * @param tol - * The tolerance value. + * @param tol + * The tolerance value. + * + * @return {@code true} if this transformation is a shift transformation + * within the given tolerance. */ public boolean isShift(double tol) { Point2D pt = transformWithoutShift(Point2D.construct(0., 1.)); @@ -521,12 +530,15 @@ public boolean isShift(double tol) { } /** - * Returns TRUE if this is an orthonormal transformation with the given + * Establishes if this is an orthonormal transformation with the given * tolerance. The orthonormal: Rotation or rotoinversion and shift * (preserves lengths of vectors and angles between vectors). * - * @param tol - * The tolerance value. + * @param tol + * The tolerance value. + * + * @return true if this is an orthonormal transformation with the given + * tolerance. */ public boolean isOrthonormal(double tol) { Transformation2D r = new Transformation2D(); @@ -541,11 +553,11 @@ public boolean isOrthonormal(double tol) { } /** - * Returns TRUE if this matrix is degenerated (does not have an inverse) - * within the given tolerance. - * - * @param tol - * The tolerance value. + * @param tol + * The tolerance value. + * + * @return true if this matrix is degenerated (does not have an inverse) + * within the given tolerance. */ public boolean isDegenerate(double tol) { return Math.abs(xx * yy - yx * xy) <= 2 * tol @@ -553,11 +565,11 @@ public boolean isDegenerate(double tol) { } /** - * Returns TRUE, if this transformation does not have rotation and shear - * within the given tolerance. - * - * @param tol - * The tolerance value. + * @param tol + * The tolerance value. + * + * @return {@code true} if this transformation does not have rotation and + * shear within the given tolerance. */ public boolean isScaleAndShift(double tol) { return xy * xy + yx * yx < (xx * xx + yy * yy) * tol; @@ -566,10 +578,11 @@ public boolean isScaleAndShift(double tol) { /** * Set this transformation to be a shift. * - * @param x - * The X coordinate to shift to. - * @param y - * The Y coordinate to shift to. + * @param x + * The X coordinate to shift to. + * + * @param y + * The Y coordinate to shift to. */ public void setShift(double x, double y) { xx = 1; @@ -583,10 +596,11 @@ public void setShift(double x, double y) { /** * Set this transformation to be a scale. * - * @param x - * The X coordinate to scale to. - * @param y - * The Y coordinate to scale to. + * @param x + * The X coordinate to scale to. + * + * @param y + * The Y coordinate to scale to. */ public void setScale(double x, double y) { xx = x; @@ -600,8 +614,8 @@ public void setScale(double x, double y) { /** * Set transformation to be a uniform scale. * - * @param _scale - * The scale of the transformation. + * @param _scale + * The scale of the transformation. */ public void setScale(double _scale) { setScale(_scale, _scale); @@ -611,10 +625,11 @@ public void setScale(double _scale) { * Sets the transformation to be a flip around the X axis. Flips the X * coordinates so that the x0 becomes x1 and vice verse. * - * @param x0 - * The X coordinate to flip. - * @param x1 - * The X coordinate to flip to. + * @param x0 + * The X coordinate to flip. + * + * @param x1 + * The X coordinate to flip to. */ public void setFlipX(double x0, double x1) { xx = -1; @@ -629,10 +644,11 @@ public void setFlipX(double x0, double x1) { * Sets the transformation to be a flip around the Y axis. Flips the Y * coordinates so that the y0 becomes y1 and vice verse. * - * @param y0 - * The Y coordinate to flip. - * @param y1 - * The Y coordinate to flip to. + * @param y0 + * The Y coordinate to flip. + * + * @param y1 + * The Y coordinate to flip to. */ public void setFlipY(double y0, double y1) { xx = 1; @@ -646,10 +662,11 @@ public void setFlipY(double y0, double y1) { /** * Set transformation to a shear. * - * @param proportionX - * The proportion of shearing in x direction. - * @param proportionY - * The proportion of shearing in y direction. + * @param proportionX + * The proportion of shearing in x direction. + * + * @param proportionY + * The proportion of shearing in y direction. */ public void setShear(double proportionX, double proportionY) { xx = 1; @@ -668,16 +685,16 @@ public void setShear(double proportionX, double proportionY) { * Y is directed down and X is directed to the right, the positive angle * corresponds to the clockwise rotation. * - * @param angle_in_Radians - * The rotation angle in radian. + * @param angle_in_Radians + * The rotation angle in radian. */ public void setRotate(double angle_in_Radians) { setRotate(Math.cos(angle_in_Radians), Math.sin(angle_in_Radians)); } /** - * Produces a transformation that swaps x and y coordinate values. xx = 0.0; - * xy = 1.0; xd = 0; yx = 1.0; yy = 0.0; yd = 0; + * @return a transformation that swaps x and y coordinate values. + * xx = 0.0; xy = 1.0; xd = 0; yx = 1.0; yy = 0.0; yd = 0; */ Transformation2D setSwapCoordinates() { xx = 0.0; @@ -697,10 +714,11 @@ Transformation2D setSwapCoordinates() { * Y is directed down and X is directed to the right, the positive angle * corresponds to the clockwise rotation. * - * @param angle_in_Radians - * The rotation angle in radian. - * @param rotationCenter - * The center point of the rotation. + * @param angle_in_Radians + * The rotation angle in radian. + * + * @param rotationCenter + * The center point of the rotation. */ void setRotate(double angle_in_Radians, Point2D rotationCenter) { setRotate(Math.cos(angle_in_Radians), Math.sin(angle_in_Radians), @@ -715,10 +733,11 @@ void setRotate(double angle_in_Radians, Point2D rotationCenter) { * Y is directed down and X is directed to the right, the positive angle * corresponds to the clockwise rotation. * - * @param cosA - * The rotation angle. - * @param sinA - * The rotation angle. + * @param cosA + * The rotation angle. + * + * @param sinA + * The rotation angle. */ public void setRotate(double cosA, double sinA) { @@ -738,12 +757,14 @@ public void setRotate(double cosA, double sinA) { * Y is directed down and X is directed to the right, the positive angle * corresponds to the clockwise rotation. * - * @param cosA - * The cos of the rotation angle. - * @param sinA - * The sin of the rotation angle. - * @param rotationCenter - * The center point of the rotation. + * @param cosA + * The cos of the rotation angle. + * + * @param sinA + * The sin of the rotation angle. + * + * @param rotationCenter + * The center point of the rotation. */ void setRotate(double cosA, double sinA, Point2D rotationCenter) { setShift(-rotationCenter.x, -rotationCenter.y); @@ -756,10 +777,11 @@ void setRotate(double cosA, double sinA, Point2D rotationCenter) { /** * Shifts the transformation. * - * @param x - * The shift factor in X direction. - * @param y - * The shift factor in Y direction. + * @param x + * The shift factor in X direction. + * + * @param y + * The shift factor in Y direction. */ public void shift(double x, double y) { xd += x; @@ -769,10 +791,11 @@ public void shift(double x, double y) { /** * Scales the transformation. * - * @param x - * The scale factor in X direction. - * @param y - * The scale factor in Y direction. + * @param x + * The scale factor in X direction. + * + * @param y + * The scale factor in Y direction. */ public void scale(double x, double y) { xx *= x; @@ -786,10 +809,11 @@ public void scale(double x, double y) { /** * Flips the transformation around the X axis. * - * @param x0 - * The X coordinate to flip. - * @param x1 - * The X coordinate to flip to. + * @param x0 + * The X coordinate to flip. + * + * @param x1 + * The X coordinate to flip to. */ public void flipX(double x0, double x1) { xx = -xx; @@ -800,10 +824,11 @@ public void flipX(double x0, double x1) { /** * Flips the transformation around the Y axis. * - * @param y0 - * The Y coordinate to flip. - * @param y1 - * The Y coordinate to flip to. + * @param y0 + * The Y coordinate to flip. + * + * @param y1 + * The Y coordinate to flip to. */ public void flipY(double y0, double y1) { yx = -yx; @@ -814,10 +839,11 @@ public void flipY(double y0, double y1) { /** * Shears the transformation. * - * @param proportionX - * The proportion of shearing in x direction. - * @param proportionY - * The proportion of shearing in y direction. + * @param proportionX + * The proportion of shearing in x direction. + * + * @param proportionY + * The proportion of shearing in y direction. */ public void shear(double proportionX, double proportionY) { Transformation2D temp = new Transformation2D(); @@ -828,8 +854,8 @@ public void shear(double proportionX, double proportionY) { /** * Rotates the transformation. * - * @param angle_in_Radians - * The rotation angle in radian. + * @param angle_in_Radians + * The rotation angle in radian. */ public void rotate(double angle_in_Radians) { Transformation2D temp = new Transformation2D(); @@ -840,10 +866,11 @@ public void rotate(double angle_in_Radians) { /** * Rotates the transformation. * - * @param cos - * The cos angle of the rotation. - * @param sin - * The sin angle of the rotation. + * @param cos + * The cos angle of the rotation. + * + * @param sin + * The sin angle of the rotation. */ public void rotate(double cos, double sin) { Transformation2D temp = new Transformation2D(); @@ -854,12 +881,14 @@ public void rotate(double cos, double sin) { /** * Rotates the transformation aroung a center point. * - * @param cos - * The cos angle of the rotation. - * @param sin - * sin angle of the rotation. - * @param rotationCenter - * The center point of the rotation. + * @param cos + * The cos angle of the rotation. + * + * @param sin + * sin angle of the rotation. + * + * @param rotationCenter + * The center point of the rotation. */ public void rotate(double cos, double sin, Point2D rotationCenter) { Transformation2D temp = new Transformation2D(); @@ -871,8 +900,8 @@ public void rotate(double cos, double sin, Point2D rotationCenter) { * Produces inverse matrix for this matrix and puts result into the inverse * parameter. * - * @param inverse - * The result inverse matrix. + * @param inverse + * The result inverse matrix. */ public void inverse(Transformation2D inverse) { double det = xx * yy - xy * yx; @@ -904,11 +933,12 @@ public void inverse() { * Extracts scaling part of the transformation. this == scale * * rotateNshearNshift. * - * @param scale - * The destination matrix where the scale part is copied. - * @param rotateNshearNshift - * The destination matrix where the part excluding rotation is - * copied. + * @param scale + * The destination matrix where the scale part is copied. + * + * @param rotateNshearNshift + * The destination matrix where the part excluding rotation is + * copied. */ public void extractScaleTransform(Transformation2D scale, Transformation2D rotateNshearNshift) { diff --git a/src/main/java/com/esri/core/geometry/VertexDescription.java b/src/main/java/com/esri/core/geometry/VertexDescription.java index 1fc1a6f6..bb193b3e 100644 --- a/src/main/java/com/esri/core/geometry/VertexDescription.java +++ b/src/main/java/com/esri/core/geometry/VertexDescription.java @@ -169,19 +169,19 @@ public interface Semantics { } /** - * Returns the attribute count of this description. The value is always - * greater or equal to 1. The first attribute is always a POSITION. + * @return the attribute count of this description. The value is always + * greater or equal to 1. The first attribute is always a POSITION. */ public final int getAttributeCount() { return m_attributeCount; } /** - * Returns the semantics of the given attribute. - * - * @param attributeIndex - * The index of the attribute in the description. Max value is - * GetAttributeCount() - 1. + * @param attributeIndex + * The index of the attribute in the description. Max value is + * GetAttributeCount() - 1. + * + * @return the semantics of the given attribute. */ public final int getSemantics(int attributeIndex) { if (attributeIndex < 0 || attributeIndex > m_attributeCount) @@ -192,46 +192,48 @@ public final int getSemantics(int attributeIndex) { /** * Returns the index the given attribute in the vertex description. - * - * @param semantics - * @return Returns the attribute index or -1 of the attribute does not exist + * + * @param semantics + * The semantics of the attribute. + * + * @return The attribute index or -1 of the attribute does not exist */ public final int getAttributeIndex(int semantics) { return m_semanticsToIndexMap[semantics]; } /** - * Returns the interpolation type for the attribute. - * - * @param semantics - * The semantics of the attribute. + * @param semantics + * The semantics of the attribute. + * + * @return The interpolation type for the attribute. */ static int getInterpolation(int semantics) { return _interpolation[semantics]; } /** - * Returns the persistence type for the attribute. - * - * @param semantics - * The semantics of the attribute. + * @param semantics + * The semantics of the attribute. + * + * @return the persistence type for the attribute. */ static int getPersistence(int semantics) { return _persistence[semantics]; } /** - * Returns the size of the persistence type in bytes. - * - * @param persistence - * The persistence type to query. + * @param persistence + * The persistence type to query. + * + * @return The size of the persistence type in bytes. */ static int getPersistenceSize(int persistence) { return _persistencesize[persistence]; } /** - * Returns the size of the semantics in bytes. + * @return The size of the semantics in bytes. */ static int getPersistenceSizeSemantics(int semantics) { return getPersistenceSize(getPersistence(semantics)) @@ -242,61 +244,67 @@ static int getPersistenceSizeSemantics(int semantics) { * Returns the number of the components of the given semantics. For example, * it returns 2 for the POSITION. * - * @param semantics - * The semantics of the attribute. + * @param semantics + * The semantics of the attribute. + * + * @return the number of the components of the given semantics */ public static int getComponentCount(int semantics) { return _components[semantics]; } /** - * Returns True for integer persistence type. + * @return {@code true} for integer persistence type. */ static boolean isIntegerPersistence(int persistence) { return persistence < Persistence.enumInt32; } /** - * Returns True for integer semantics type. + * @return {@code true} for integer semantics type. */ static boolean isIntegerSemantics(int semantics) { return isIntegerPersistence(getPersistence(semantics)); } /** - * Returns True if the attribute with the given name and given set exists. - * - * @param semantics - * The semantics of the attribute. + * @param semantics + * The semantics of the attribute. + * + * @return {@code true} if the attribute with the given name and given set + * exists. */ public boolean hasAttribute(int semantics) { return m_semanticsToIndexMap[semantics] >= 0; } /** - * Returns True, if the vertex has Z attribute. + * @return {@code true} if the vertex has Z attribute. */ public boolean hasZ() { return hasAttribute(Semantics.Z); } /** - * Returns True, if the vertex has M attribute. + * @return {@code true} if the vertex has M attribute. */ public boolean hasM() { return hasAttribute(Semantics.M); } /** - * Returns True, if the vertex has ID attribute. + * @return {@code true} if the vertex has ID attribute. */ public boolean hasID() { return hasAttribute(Semantics.ID); } /** - * Returns default value for each ordinate of the vertex attribute with - * given semantics. + * @param semantics + * the semantics value to obtain default values for + * + * @return default value for each ordinate of the vertex attribute with + * given semantics. */ public static double getDefaultValue(int semantics) { return _defaultValues[semantics]; @@ -307,7 +315,7 @@ int getPointAttributeOffset_(int attribute_index) { } /** - * Returns the total component count. + * @return the total component count. */ public int getTotalComponentCount() { return m_total_component_count; @@ -317,6 +325,14 @@ public int getTotalComponentCount() { * Checks if the given value is the default one. The simple equality test * with GetDefaultValue does not work due to the use of NaNs as default * value for some parameters. + * + * @param semantics + * the semantics value to obtain default values for + * + * @param v + * the value under test + * + * @return {@code true} if the given value is equal to default value */ public static boolean isDefaultValue(int semantics, double v) { return NumberUtils.doubleToInt64Bits(_defaultValues[semantics]) == NumberUtils @@ -346,9 +362,9 @@ int calculateHashImpl() { } /** - * - * Returns a packed array of double representation of all ordinates of - * attributes of a point, i.e.: X, Y, Z, ID, TEXTURE2D.u, TEXTURE2D.v + * @return a packed array of double representation of all ordinates of + * attributes of a point, i.e.: X, Y, Z, ID, TEXTURE2D.u, + * TEXTURE2D.v */ double[] _getDefaultPointAttributes() { return m_defaultPointAttributes; @@ -364,6 +380,11 @@ int calculateHashImpl() { * Returns an offset to the first ordinate of the given attribute. This * method is used for the cases when one wants to have a packed array of * ordinates of all attributes, i.e.: X, Y, Z, ID, TEXTURE2D.u, TEXTURE2D.v + * + * @param attributeIndex + * the required attribute index + * + * @return an offset to the first ordinate of the given attribute */ int _getPointAttributeOffset(int attributeIndex) { return m_pointAttributeOffsets[attributeIndex]; diff --git a/src/main/java/com/esri/core/geometry/ogc/OGCGeometry.java b/src/main/java/com/esri/core/geometry/ogc/OGCGeometry.java index 9783bb94..41e433e6 100644 --- a/src/main/java/com/esri/core/geometry/ogc/OGCGeometry.java +++ b/src/main/java/com/esri/core/geometry/ogc/OGCGeometry.java @@ -143,7 +143,7 @@ public double MaxMeasure() { * For non-simple geometries, it terminates immediately when the first issue * is encountered. * - * @return True if geometry is simple and false otherwise. + * @return {@code true} if geometry is simple and false otherwise. * * Note: If isSimple is true, then isSimpleRelaxed is true too. */ @@ -174,6 +174,9 @@ public OGCGeometry MakeSimpleRelaxed(boolean forceProcessing) { } /** * Makes a simple geometry for Geodatabase. + * + * @param forceProcessing true if the Geometry should be simplified + * regardless of the internal IsKnownSimple flag. * * @return Returns simplified geometry. * @@ -211,8 +214,11 @@ public boolean isMeasured() { abstract public OGCGeometry boundary(); /** - * OGC equals - * + * @param another + * The {@code OGCGeometry} to compare this against + * + * @return {@code true} if the given OGC geometry is equivalent to this + * OGC geometry, {@code false} otherwise */ public boolean equals(OGCGeometry another) { com.esri.core.geometry.Geometry geom1 = getEsriGeometry(); @@ -437,8 +443,8 @@ public com.esri.core.geometry.SpatialReference getEsriSpatialReference() { /** * Create an OGCGeometry instance from the GeometryCursor. * - * @param gc - * @param sr + * @param gc cursor to a geometry + * @param sr spatial reference of the given geometry * @return Geometry instance created from the geometry cursor. */ public static OGCGeometry createFromEsriCursor(GeometryCursor gc, diff --git a/src/main/java/com/esri/core/geometry/ogc/OGCGeometryCollection.java b/src/main/java/com/esri/core/geometry/ogc/OGCGeometryCollection.java index ea0d84af..1e9ffcc3 100644 --- a/src/main/java/com/esri/core/geometry/ogc/OGCGeometryCollection.java +++ b/src/main/java/com/esri/core/geometry/ogc/OGCGeometryCollection.java @@ -2,13 +2,15 @@ public abstract class OGCGeometryCollection extends OGCGeometry { /** - * Returns the number of geometries in this GeometryCollection. + * @return the number of geometries in this GeometryCollection. */ public abstract int numGeometries(); /** - * Returns the Nth geometry in this GeometryCollection. - * @param n The 0 based index of the geometry. + * @param n + * The 0 based index of the geometry. + * + * @return the Nth geometry in this GeometryCollection. */ public abstract OGCGeometry geometryN(int n); } diff --git a/src/main/java/com/esri/core/geometry/ogc/OGCLineString.java b/src/main/java/com/esri/core/geometry/ogc/OGCLineString.java index eb3ee7bb..43fc4e01 100644 --- a/src/main/java/com/esri/core/geometry/ogc/OGCLineString.java +++ b/src/main/java/com/esri/core/geometry/ogc/OGCLineString.java @@ -14,7 +14,7 @@ public class OGCLineString extends OGCCurve { /** - * The number of Points in this LineString. + * @return the number of Points in this LineString. */ public int numPoints() { if (multiPath.isEmpty()) @@ -38,8 +38,10 @@ public ByteBuffer asBinary() { } /** - * Returns the specified Point N in this LineString. - * @param n The 0 based index of the Point. + * @param n + * The 0 based index of the Point. + * + * @return the specified Point N in this LineString. */ public OGCPoint pointN(int n) { int nn; diff --git a/src/main/java/com/esri/core/geometry/ogc/OGCMultiPoint.java b/src/main/java/com/esri/core/geometry/ogc/OGCMultiPoint.java index a57c3b4e..548402bf 100644 --- a/src/main/java/com/esri/core/geometry/ogc/OGCMultiPoint.java +++ b/src/main/java/com/esri/core/geometry/ogc/OGCMultiPoint.java @@ -45,9 +45,11 @@ public String geometryType() { } /** - * - * @param mp - * MultiPoint instance will be referenced by this OGC class + * @param mp + * MultiPoint instance will be referenced by this OGC class + * + * @param sr + * Spatial reference for the given {@link MultiPoint} */ public OGCMultiPoint(MultiPoint mp, SpatialReference sr) { multiPoint = mp; diff --git a/src/main/java/com/esri/core/geometry/ogc/OGCPolygon.java b/src/main/java/com/esri/core/geometry/ogc/OGCPolygon.java index 5a038d2a..88ffc2e8 100644 --- a/src/main/java/com/esri/core/geometry/ogc/OGCPolygon.java +++ b/src/main/java/com/esri/core/geometry/ogc/OGCPolygon.java @@ -57,7 +57,7 @@ public OGCLineString exteriorRing() { } /** - * Returns the number of interior rings in this Polygon. + * @return the number of interior rings in this Polygon. */ public int numInteriorRing() { return polygon.getPathCount() - 1;