Reconstruct a geometry, feature, feature collection, or nested vectors of either using the function f on the target trait.
f(target_geom) => x where x also has the target trait, or a trait that can be substituted. For example, swapping PolgonTrait to MultiPointTrait will fail if the outer object has MultiPolygonTrait, but should work if it has FeatureTrait.
Objects "shallower" than the target trait are always completely rebuilt, like a Vector of FeatureCollectionTrait of FeatureTrait when the target has PolygonTrait and is held in the features. These will always be GeoInterface geometries/feature/feature collections. But "deeper" objects may remain unchanged or be whatever GeoInterface compatible objects f returns.
The result is a functionally similar geometry with values depending on f.
threaded: true or false. Whether to use multithreading. Defaults to false.
crs: The CRS to attach to geometries. Defaults to nothing.
calc_extent: true or false. Whether to calculate the extent. Defaults to false.
Example
Flipped point the order in any feature or geometry, or iterables of either:
julia
import GeoInterface as GI
+import GeometryOps as GO
+geom = GI.Polygon([GI.LinearRing([(1, 2), (3, 4), (5, 6), (1, 2)]),
+ GI.LinearRing([(3, 4), (5, 6), (6, 7), (3, 4)])])
+
+flipped_geom = GO.apply(GI.PointTrait, geom) do p
+ (GI.y(p), GI.x(p))
+end
Reproject any GeoInterface.jl compatible geometry from source_crs to target_crs.
The returned object will be constructed from GeoInterface.WrapperGeometry geometries, wrapping views of a Vector{Proj.Point{D}}, where D is the dimension.
Tip
The Proj.jl package must be loaded for this method to work, since it is implemented in a package extension.
Arguments
geometry: Any GeoInterface.jl compatible geometries.
source_crs: the source coordinate referece system, as a GeoFormatTypes.jl object or a string.
target_crs: the target coordinate referece system, as a GeoFormatTypes.jl object or a string.
If these a passed as keywords, transform will take priority. Without it target_crs is always needed, and source_crs is needed if it is not retreivable from the geometry with GeoInterface.crs(geometry).
Keywords
always_xy: force x, y coordinate order, true by default. false will expect and return points in the crs coordinate order.
time: the time for the coordinates. Inf by default.
threaded: true or false. Whether to use multithreading. Defaults to false.
crs: The CRS to attach to geometries. Defaults to nothing.
calc_extent: true or false. Whether to calculate the extent. Defaults to false.
Return true if the second geometry is completely contained by the first geometry. The interiors of both geometries must intersect and the interior and boundary of the secondary (g2) must not intersect the exterior of the first (g1).
contains returns the exact opposite result of within.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = GI.Point((1, 2))
+
+GO.contains(line, point)
+# output
+true
Return true if the first geometry is completely covered by the second geometry. The interior and boundary of the primary geometry (g1) must not intersect the exterior of the secondary geometry (g2).
Furthermore, coveredby returns the exact opposite result of covers. They are equivalent with the order of the arguments swapped.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+p1 = GI.Point(0.0, 0.0)
+p2 = GI.Point(1.0, 1.0)
+l1 = GI.Line([p1, p2])
+
+GO.coveredby(p1, l1)
+# output
+true
Return true if the first geometry is completely covers the second geometry, The exterior and boundary of the second geometry must not be outside of the interior and boundary of the first geometry. However, the interiors need not intersect.
covers returns the exact opposite result of coveredby.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+l1 = GI.LineString([(1.0, 1.0), (1.0, 2.0), (1.0, 3.0), (1.0, 4.0)])
+l2 = GI.LineString([(1.0, 1.0), (1.0, 2.0)])
+
+GO.covers(l1, l2)
+# output
+true
Return true if the intersection results in a geometry whose dimension is one less than the maximum dimension of the two source geometries and the intersection set is interior to both source geometries.
TODO: broken
Examples
julia
import GeoInterface as GI, GeometryOps as GO
+# TODO: Add working example
Compare two Geometries of the same dimension and return true if their intersection set results in a geometry different from both but of the same dimension. This means one geometry cannot be within or contain the other and they cannot be equal
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+poly1 = GI.Polygon([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+poly2 = GI.Polygon([[(1,1), (1,6), (6,6), (6,1), (1,1)]])
+
+GO.overlaps(poly1, poly2)
+# output
+true
Return true if the first geometry touches the second geometry. In other words, the two interiors cannot interact, but one of the geometries must have a boundary point that interacts with either the other geometies interior or boundary.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+
+l1 = GI.Line([(0.0, 0.0), (1.0, 0.0)])
+l2 = GI.Line([(1.0, 1.0), (1.0, -1.0)])
+
+GO.touches(l1, l2)
+# output
+true
Return true if the first geometry is completely within the second geometry. The interiors of both geometries must intersect and the interior and boundary of the primary geometry (geom1) must not intersect the exterior of the secondary geometry (geom2).
Furthermore, within returns the exact opposite result of contains.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = (1, 2)
+GO.within(point, line)
+
+# output
+true
A line/linestring and a linear ring are equal if they share the same set of points going along the curve. Note that lines aren't closed by defintion, but rings are, so the line must have a repeated last point to be equal
A linear ring and a line/linestring are equal if they share the same set of points going along the curve. Note that lines aren't closed by defintion, but rings are, so the line must have a repeated last point to be equal
Two linear rings are equal if they share the same set of points going along the curve. Note that rings are closed by definition, so they can have, but don't need, a repeated last point to be equal.
Calculates the ditance from the geometry g1 to the point. The distance will always be positive or zero.
The method will differ based on the type of the geometry provided: - The distance from a point to a point is just the Euclidean distance between the points. - The distance from a point to a line is the minimum distance from the point to the closest point on the given line. - The distance from a point to a linestring is the minimum distance from the point to the closest segment of the linestring. - The distance from a point to a linear ring is the minimum distance from the point to the closest segment of the linear ring. - The distance from a point to a polygon is zero if the point is within the polygon and otherwise is the minimum distance from the point to an edge of the polygon. This includes edges created by holes. - The distance from a point to a multigeometry or a geometry collection is the minimum distance between the point and any of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Calculates the signed distance from the geometry geom to the given point. Points within geom have a negative signed distance, and points outside of geom have a positive signed distance. - The signed distance from a point to a point, line, linestring, or linear ring is equal to the distance between the two. - The signed distance from a point to a polygon is negative if the point is within the polygon and is positive otherwise. The value of the distance is the minimum distance from the point to an edge of the polygon. This includes edges created by holes. - The signed distance from a point to a multigeometry or a geometry collection is the minimum signed distance between the point and any of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Returns the area of a geometry or collection of geometries. This is computed slightly differently for different geometries:
- The area of a point/multipoint is always zero.
+- The area of a curve/multicurve is always zero.
+- The area of a polygon is the absolute value of the signed area.
+- The area multi-polygon is the sum of the areas of all of the sub-polygons.
+- The area of a geometry collection, feature collection of array/iterable
+ is the sum of the areas of all of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Returns the signed area of a single geometry, based on winding order. This is computed slighly differently for different geometries:
- The signed area of a point is always zero.
+- The signed area of a curve is always zero.
+- The signed area of a polygon is computed with the shoelace formula and is
+positive if the polygon coordinates wind clockwise and negative if
+counterclockwise.
+- You cannot compute the signed area of a multipolygon as it doesn't have a
+meaning as each sub-polygon could have a different winding order.
Result will be of type T, where T is an optional argument with a default value of Float64.
Returns the angles of a geometry or collection of geometries. This is computed differently for different geometries:
- The angles of a point is an empty vector.
+- The angles of a single line segment is an empty vector.
+- The angles of a linestring or linearring is a vector of angles formed by the curve.
+- The angles of a polygin is a vector of vectors of angles formed by each ring.
+- The angles of a multi-geometry collection is a vector of the angles of each of the
+ sub-geometries as defined above.
Result will be a Vector, or nested set of vectors, of type T where an optional argument with a default value of Float64.
Recursively wrap the object with a GeoInterface.jl geometry, calculating and adding an Extents.Extent to all objects.
This can improve performance when extents need to be checked multiple times, such when needing to check if many points are in geometries, and using their extents as a quick filter for obviously exterior points.
Keywords
threaded: true or false. Whether to use multithreading. Defaults to false.
crs: The CRS to attach to geometries. Defaults to nothing.
Returns the interpolated value at point within polygon using the barycentric coordinate method method. values are the per-point values for the polygon which are to be interpolated.
Returns an object of type V.
Warning
Barycentric interpolation is currently defined only for 2-dimensional polygons. If you pass a 3-D polygon in, the Z coordinate will be used as per-vertex value to be interpolated (the M coordinate in GIS parlance).
Abstract supertype for barycentric coordinate methods. The subtypes may serve as dispatch types, or may cache some information about the target polygon.
API
The following methods must be implemented for all subtypes:
This correction ensures that the polygons included in a multipolygon aren't intersecting. If any polygon's are intersecting, they will be made nonintersecting through the difference operation to create a unique set of disjoint (other than potentially connections by a single point) polygons covering the same area. See also GeometryCorrection, UnionIntersectingPolygons.
A method for segmentizing geometries by adding extra vertices to the geometry so that no segment is longer than a given distance. This method calculates the distance between points on the geodesic, and assumes input in lat/long coordinates.
Warning
Any input geometries must be in lon/lat coordinates! If not, the method may fail or error.
Arguments
max_distance::Real: The maximum distance, in meters, between vertices in the geometry.
equatorial_radius::Real=6378137: The equatorial radius of the Earth, in meters. Passed to Proj.geod_geodesic.
flattening::Real=1/298.257223563: The flattening of the Earth, which is the ratio of the difference between the equatorial and polar radii to the equatorial radius. Passed to Proj.geod_geodesic.
One can also omit the equatorial_radius and flattening keyword arguments, and pass a geodesic object directly to the eponymous keyword.
This method uses the Proj/GeographicLib API for geodesic calculations.
This abstract type represents a geometry correction.
Interface
Any GeometryCorrection must implement two functions: * application_level(::GeometryCorrection)::AbstractGeometryTrait: This function should return the GeoInterface trait that the correction is intended to be applied to, like PointTrait or LineStringTrait or PolygonTrait. * (::GeometryCorrection)(::AbstractGeometryTrait, geometry)::(some_geometry): This function should apply the correction to the given geometry, and return a new geometry.
Enum for the orientation of a line with respect to a curve. A line can be line_cross (crossing over the curve), line_hinge (crossing the endpoint of the curve), line_over (colinear with the curve), or line_out (not interacting with the curve).
A method for segmentizing geometries by adding extra vertices to the geometry so that no segment is longer than a given distance.
Here, max_distance is a purely nondimensional quantity and will apply in the input space. This is to say, that if the polygon is provided in lat/lon coordinates then the max_distance will be in degrees of arc. If the polygon is provided in meters, then the max_distance will be in meters.
This struct holds a trait parameter or a union of trait parameters.
It is primarily used for dispatch into methods which select trait levels, like apply, or as a parameter to target.
Constructors
julia
TraitTarget(GI.PointTrait())
+TraitTarget(GI.LineStringTrait(), GI.LinearRingTrait()) # and other traits as you may like
+TraitTarget(TraitTarget(...))
+# There are also type based constructors available, but that's not advised.
+TraitTarget(GI.PointTrait)
+TraitTarget(Union{GI.LineStringTrait, GI.LinearRingTrait})
+# etc.
This correction ensures that the polygon's included in a multipolygon aren't intersecting. If any polygon's are intersecting, they will be combined through the union operation to create a unique set of disjoint (other than potentially connections by a single point) polygons covering the same area.
Two curves are equal if they share the same set of point, representing the same geometry. Both curves must must be composed of the same set of points, however, they do not have to wind in the same direction, or start on the same point to be equivalent. Inputs: c1 first geometry c2 second geometry closed_type1::Bool true if c1 is closed by definition (polygon, linear ring) closed_type2::Bool true if c2 is closed by definition (polygon, linear ring)
Returns the angles of a geometry or collection of geometries. This is computed differently for different geometries:
- The angles of a point is an empty vector.
+- The angles of a single line segment is an empty vector.
+- The angles of a linestring or linearring is a vector of angles formed by the curve.
+- The angles of a polygin is a vector of vectors of angles formed by each ring.
+- The angles of a multi-geometry collection is a vector of the angles of each of the
+ sub-geometries as defined above.
Result will be a Vector, or nested set of vectors, of type T where an optional argument with a default value of Float64.
Reconstruct a geometry, feature, feature collection, or nested vectors of either using the function f on the target trait.
f(target_geom) => x where x also has the target trait, or a trait that can be substituted. For example, swapping PolgonTrait to MultiPointTrait will fail if the outer object has MultiPolygonTrait, but should work if it has FeatureTrait.
Objects "shallower" than the target trait are always completely rebuilt, like a Vector of FeatureCollectionTrait of FeatureTrait when the target has PolygonTrait and is held in the features. These will always be GeoInterface geometries/feature/feature collections. But "deeper" objects may remain unchanged or be whatever GeoInterface compatible objects f returns.
The result is a functionally similar geometry with values depending on f.
threaded: true or false. Whether to use multithreading. Defaults to false.
crs: The CRS to attach to geometries. Defaults to nothing.
calc_extent: true or false. Whether to calculate the extent. Defaults to false.
Example
Flipped point the order in any feature or geometry, or iterables of either:
julia
import GeoInterface as GI
+import GeometryOps as GO
+geom = GI.Polygon([GI.LinearRing([(1, 2), (3, 4), (5, 6), (1, 2)]),
+ GI.LinearRing([(3, 4), (5, 6), (6, 7), (3, 4)])])
+
+flipped_geom = GO.apply(GI.PointTrait, geom) do p
+ (GI.y(p), GI.x(p))
+end
Returns the area of a geometry or collection of geometries. This is computed slightly differently for different geometries:
- The area of a point/multipoint is always zero.
+- The area of a curve/multicurve is always zero.
+- The area of a polygon is the absolute value of the signed area.
+- The area multi-polygon is the sum of the areas of all of the sub-polygons.
+- The area of a geometry collection, feature collection of array/iterable
+ is the sum of the areas of all of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Returns the interpolated value at point within polygon using the barycentric coordinate method method. values are the per-point values for the polygon which are to be interpolated.
Returns an object of type V.
Warning
Barycentric interpolation is currently defined only for 2-dimensional polygons. If you pass a 3-D polygon in, the Z coordinate will be used as per-vertex value to be interpolated (the M coordinate in GIS parlance).
Return true if the second geometry is completely contained by the first geometry. The interiors of both geometries must intersect and the interior and boundary of the secondary (g2) must not intersect the exterior of the first (g1).
contains returns the exact opposite result of within.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = GI.Point((1, 2))
+
+GO.contains(line, point)
+# output
+true
Returns the area of intersection between given geometry and grid cell defined by its minimum and maximum x and y-values. This is computed differently for different geometries:
The signed area of a point is always zero.
The signed area of a curve is always zero.
The signed area of a polygon is calculated by tracing along its edges and switching to the cell edges if needed.
The coverage of a geometry collection, multi-geometry, feature collection of array/iterable is the sum of the coverages of all of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Return true if the first geometry is completely covered by the second geometry. The interior and boundary of the primary geometry (g1) must not intersect the exterior of the secondary geometry (g2).
Furthermore, coveredby returns the exact opposite result of covers. They are equivalent with the order of the arguments swapped.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+p1 = GI.Point(0.0, 0.0)
+p2 = GI.Point(1.0, 1.0)
+l1 = GI.Line([p1, p2])
+
+GO.coveredby(p1, l1)
+# output
+true
Return true if the first geometry is completely covers the second geometry, The exterior and boundary of the second geometry must not be outside of the interior and boundary of the first geometry. However, the interiors need not intersect.
covers returns the exact opposite result of coveredby.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+l1 = GI.LineString([(1.0, 1.0), (1.0, 2.0), (1.0, 3.0), (1.0, 4.0)])
+l2 = GI.LineString([(1.0, 1.0), (1.0, 2.0)])
+
+GO.covers(l1, l2)
+# output
+true
Return true if the intersection results in a geometry whose dimension is one less than the maximum dimension of the two source geometries and the intersection set is interior to both source geometries.
TODO: broken
Examples
julia
import GeoInterface as GI, GeometryOps as GO
+# TODO: Add working example
Return given geom cut by given line as a list of geometries of the same type as the input geom. Return the original geometry as only list element if none are found. Line must cut fully through given geometry or the original geometry will be returned.
Note: This currently doesn't work for degenerate cases there line crosses through vertices.
Return the difference between two geometries as a list of geometries. Return an empty list if none are found. The type of the list will be constrained as much as possible given the input geometries. Furthermore, the user can provide a taget type as a keyword argument and a list of target geometries found in the difference will be returned. The user can also provide a float type that they would like the points of returned geometries to be. If the user is taking a intersection involving one or more multipolygons, and the multipolygon might be comprised of polygons that intersect, if fix_multipoly is set to an IntersectingPolygons correction (the default is UnionIntersectingPolygons()), then the needed multipolygons will be fixed to be valid before performing the intersection to ensure a correct answer. Only set fix_multipoly to false if you know that the multipolygons are valid, as it will avoid unneeded computation.
Calculates the ditance from the geometry g1 to the point. The distance will always be positive or zero.
The method will differ based on the type of the geometry provided: - The distance from a point to a point is just the Euclidean distance between the points. - The distance from a point to a line is the minimum distance from the point to the closest point on the given line. - The distance from a point to a linestring is the minimum distance from the point to the closest segment of the linestring. - The distance from a point to a linear ring is the minimum distance from the point to the closest segment of the linear ring. - The distance from a point to a polygon is zero if the point is within the polygon and otherwise is the minimum distance from the point to an edge of the polygon. This includes edges created by holes. - The distance from a point to a multigeometry or a geometry collection is the minimum distance between the point and any of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Recursively wrap the object with a GeoInterface.jl geometry, calculating and adding an Extents.Extent to all objects.
This can improve performance when extents need to be checked multiple times, such when needing to check if many points are in geometries, and using their extents as a quick filter for obviously exterior points.
Keywords
threaded: true or false. Whether to use multithreading. Defaults to false.
crs: The CRS to attach to geometries. Defaults to nothing.
Two linear rings are equal if they share the same set of points going along the curve. Note that rings are closed by definition, so they can have, but don't need, a repeated last point to be equal.
A linear ring and a line/linestring are equal if they share the same set of points going along the curve. Note that lines aren't closed by defintion, but rings are, so the line must have a repeated last point to be equal
A line/linestring and a linear ring are equal if they share the same set of points going along the curve. Note that lines aren't closed by defintion, but rings are, so the line must have a repeated last point to be equal
Lazily flatten any AbstractArray, iterator, FeatureCollectionTrait, FeatureTrait or AbstractGeometryTrait object obj, so that objects with the target trait are returned by the iterator.
If f is passed in it will be applied to the target geometries.
Return the intersection between two geometries as a list of geometries. Return an empty list if none are found. The type of the list will be constrained as much as possible given the input geometries. Furthermore, the user can provide a target type as a keyword argument and a list of target geometries found in the intersection will be returned. The user can also provide a float type that they would like the points of returned geometries to be. If the user is taking a intersection involving one or more multipolygons, and the multipolygon might be comprised of polygons that intersect, if fix_multipoly is set to an IntersectingPolygons correction (the default is UnionIntersectingPolygons()), then the needed multipolygons will be fixed to be valid before performing the intersection to ensure a correct answer. Only set fix_multipoly to nothing if you know that the multipolygons are valid, as it will avoid unneeded computation.
Return a list of intersection points between two geometries of type GI.Point. If no intersection point was possible given geometry extents, returns an empty list.
Compare two Geometries of the same dimension and return true if their intersection set results in a geometry different from both but of the same dimension. This means one geometry cannot be within or contain the other and they cannot be equal
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+poly1 = GI.Polygon([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+poly2 = GI.Polygon([[(1,1), (1,6), (6,6), (6,1), (1,1)]])
+
+GO.overlaps(poly1, poly2)
+# output
+true
Polygonize an AbstractMatrix of values, currently to a single class of polygons.
Returns a MultiPolygon for Bool values and f return values, and a FeatureCollection of Features holding MultiPolygon for all other values.
Function f should return either true or false or a transformation of values into simpler groups, especially useful for floating point arrays.
If xs and ys are ranges, they are used as the pixel/cell center points. If they are Vector of Tuple they are used as the lower and upper bounds of each pixel/cell.
Keywords
minpoints: ignore polygons with less than minpoints points.
values: the values to turn into polygons. By default these are union(A), If function f is passed these refer to the return values of f, by default union(map(f, A). If values Bool, false is ignored and a single MultiPolygon is returned rather than a FeatureCollection.
Example
julia
using GeometryOps
+A = rand(100, 100)
+multipolygon = polygonize(>(0.5), A);
By default geometries will be rebuilt as a GeoInterface.Wrappers geometry, but rebuild can have methods added to it to dispatch on geometries from other packages and specify how to rebuild them.
Segmentize a geometry by adding extra vertices to the geometry so that no segment is longer than a given distance. This is useful for plotting geometries with a limited number of vertices, or for ensuring that a geometry is not too "coarse" for a given application.
Arguments
method::SegmentizeMethod = LinearSegments(): The method to use for segmentizing the geometry. At the moment, only LinearSegments and GeodesicSegments are available.
geom: The geometry to segmentize. Must be a LineString, LinearRing, or greater in complexity.
max_distance::Real: The maximum distance, in the input space, between vertices in the geometry. Only used if you don't explicitly pass a method.
Returns a geometry of similar type to the input geometry, but resampled.
Returns the signed area of a single geometry, based on winding order. This is computed slighly differently for different geometries:
- The signed area of a point is always zero.
+- The signed area of a curve is always zero.
+- The signed area of a polygon is computed with the shoelace formula and is
+positive if the polygon coordinates wind clockwise and negative if
+counterclockwise.
+- You cannot compute the signed area of a multipolygon as it doesn't have a
+meaning as each sub-polygon could have a different winding order.
Result will be of type T, where T is an optional argument with a default value of Float64.
Calculates the signed distance from the geometry geom to the given point. Points within geom have a negative signed distance, and points outside of geom have a positive signed distance. - The signed distance from a point to a point, line, linestring, or linear ring is equal to the distance between the two. - The signed distance from a point to a polygon is negative if the point is within the polygon and is positive otherwise. The value of the distance is the minimum distance from the point to an edge of the polygon. This includes edges created by holes. - The signed distance from a point to a multigeometry or a geometry collection is the minimum signed distance between the point and any of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Return true if the first geometry touches the second geometry. In other words, the two interiors cannot interact, but one of the geometries must have a boundary point that interacts with either the other geometies interior or boundary.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+
+l1 = GI.Line([(0.0, 0.0), (1.0, 0.0)])
+l2 = GI.Line([(1.0, 1.0), (1.0, -1.0)])
+
+GO.touches(l1, l2)
+# output
+true
Return the union between two geometries as a list of geometries. Return an empty list if none are found. The type of the list will be constrained as much as possible given the input geometries. Furthermore, the user can provide a taget type as a keyword argument and a list of target geometries found in the difference will be returned. The user can also provide a float type 'T' that they would like the points of returned geometries to be. If the user is taking a intersection involving one or more multipolygons, and the multipolygon might be comprised of polygons that intersect, if fix_multipoly is set to an IntersectingPolygons correction (the default is UnionIntersectingPolygons()), then the needed multipolygons will be fixed to be valid before performing the intersection to ensure a correct answer. Only set fix_multipoly to false if you know that the multipolygons are valid, as it will avoid unneeded computation.
Return true if the first geometry is completely within the second geometry. The interiors of both geometries must intersect and the interior and boundary of the primary geometry (geom1) must not intersect the exterior of the secondary geometry (geom2).
Furthermore, within returns the exact opposite result of contains.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = (1, 2)
+GO.within(point, line)
+
+# output
+true
K. Hormann and N. Sukumar. Generalized Barycentric Coordinates in Computer Graphics and Computational Mechanics. Taylor & Fancis, CRC Press, 2017. ↩︎
+
+
+
+
\ No newline at end of file
diff --git a/previews/PR149/assets/agabzyz.DC3TvBOO.png b/previews/PR149/assets/agabzyz.DC3TvBOO.png
new file mode 100644
index 000000000..924b99908
Binary files /dev/null and b/previews/PR149/assets/agabzyz.DC3TvBOO.png differ
diff --git a/previews/PR149/assets/api.md.Dpn612f9.js b/previews/PR149/assets/api.md.Dpn612f9.js
new file mode 100644
index 000000000..db8b4f72d
--- /dev/null
+++ b/previews/PR149/assets/api.md.Dpn612f9.js
@@ -0,0 +1,387 @@
+import{_ as n,c as e,j as s,a,a6 as i,o as t}from"./chunks/framework.CDOaXZPW.js";const O=JSON.parse('{"title":"Full GeometryOps API documentation","description":"","frontmatter":{},"headers":[],"relativePath":"api.md","filePath":"api.md","lastUpdated":null}'),l={name:"api.md"},h=i(`
Reconstruct a geometry, feature, feature collection, or nested vectors of either using the function f on the target trait.
f(target_geom) => x where x also has the target trait, or a trait that can be substituted. For example, swapping PolgonTrait to MultiPointTrait will fail if the outer object has MultiPolygonTrait, but should work if it has FeatureTrait.
Objects "shallower" than the target trait are always completely rebuilt, like a Vector of FeatureCollectionTrait of FeatureTrait when the target has PolygonTrait and is held in the features. These will always be GeoInterface geometries/feature/feature collections. But "deeper" objects may remain unchanged or be whatever GeoInterface compatible objects f returns.
The result is a functionally similar geometry with values depending on f.
threaded: true or false. Whether to use multithreading. Defaults to false.
crs: The CRS to attach to geometries. Defaults to nothing.
calc_extent: true or false. Whether to calculate the extent. Defaults to false.
Example
Flipped point the order in any feature or geometry, or iterables of either:
julia
import GeoInterface as GI
+import GeometryOps as GO
+geom = GI.Polygon([GI.LinearRing([(1, 2), (3, 4), (5, 6), (1, 2)]),
+ GI.LinearRing([(3, 4), (5, 6), (6, 7), (3, 4)])])
+
+flipped_geom = GO.apply(GI.PointTrait, geom) do p
+ (GI.y(p), GI.x(p))
+end
Reproject any GeoInterface.jl compatible geometry from source_crs to target_crs.
The returned object will be constructed from GeoInterface.WrapperGeometry geometries, wrapping views of a Vector{Proj.Point{D}}, where D is the dimension.
Tip
The Proj.jl package must be loaded for this method to work, since it is implemented in a package extension.
Arguments
geometry: Any GeoInterface.jl compatible geometries.
source_crs: the source coordinate referece system, as a GeoFormatTypes.jl object or a string.
target_crs: the target coordinate referece system, as a GeoFormatTypes.jl object or a string.
If these a passed as keywords, transform will take priority. Without it target_crs is always needed, and source_crs is needed if it is not retreivable from the geometry with GeoInterface.crs(geometry).
Keywords
always_xy: force x, y coordinate order, true by default. false will expect and return points in the crs coordinate order.
time: the time for the coordinates. Inf by default.
threaded: true or false. Whether to use multithreading. Defaults to false.
crs: The CRS to attach to geometries. Defaults to nothing.
calc_extent: true or false. Whether to calculate the extent. Defaults to false.
Return true if the second geometry is completely contained by the first geometry. The interiors of both geometries must intersect and the interior and boundary of the secondary (g2) must not intersect the exterior of the first (g1).
contains returns the exact opposite result of within.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = GI.Point((1, 2))
+
+GO.contains(line, point)
+# output
+true
Return true if the first geometry is completely covered by the second geometry. The interior and boundary of the primary geometry (g1) must not intersect the exterior of the secondary geometry (g2).
Furthermore, coveredby returns the exact opposite result of covers. They are equivalent with the order of the arguments swapped.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+p1 = GI.Point(0.0, 0.0)
+p2 = GI.Point(1.0, 1.0)
+l1 = GI.Line([p1, p2])
+
+GO.coveredby(p1, l1)
+# output
+true
Return true if the first geometry is completely covers the second geometry, The exterior and boundary of the second geometry must not be outside of the interior and boundary of the first geometry. However, the interiors need not intersect.
covers returns the exact opposite result of coveredby.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+l1 = GI.LineString([(1.0, 1.0), (1.0, 2.0), (1.0, 3.0), (1.0, 4.0)])
+l2 = GI.LineString([(1.0, 1.0), (1.0, 2.0)])
+
+GO.covers(l1, l2)
+# output
+true
Return true if the intersection results in a geometry whose dimension is one less than the maximum dimension of the two source geometries and the intersection set is interior to both source geometries.
TODO: broken
Examples
julia
import GeoInterface as GI, GeometryOps as GO
+# TODO: Add working example
Compare two Geometries of the same dimension and return true if their intersection set results in a geometry different from both but of the same dimension. This means one geometry cannot be within or contain the other and they cannot be equal
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+poly1 = GI.Polygon([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+poly2 = GI.Polygon([[(1,1), (1,6), (6,6), (6,1), (1,1)]])
+
+GO.overlaps(poly1, poly2)
+# output
+true
Return true if the first geometry touches the second geometry. In other words, the two interiors cannot interact, but one of the geometries must have a boundary point that interacts with either the other geometies interior or boundary.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+
+l1 = GI.Line([(0.0, 0.0), (1.0, 0.0)])
+l2 = GI.Line([(1.0, 1.0), (1.0, -1.0)])
+
+GO.touches(l1, l2)
+# output
+true
Return true if the first geometry is completely within the second geometry. The interiors of both geometries must intersect and the interior and boundary of the primary geometry (geom1) must not intersect the exterior of the secondary geometry (geom2).
Furthermore, within returns the exact opposite result of contains.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = (1, 2)
+GO.within(point, line)
+
+# output
+true
A line/linestring and a linear ring are equal if they share the same set of points going along the curve. Note that lines aren't closed by defintion, but rings are, so the line must have a repeated last point to be equal
A linear ring and a line/linestring are equal if they share the same set of points going along the curve. Note that lines aren't closed by defintion, but rings are, so the line must have a repeated last point to be equal
Two linear rings are equal if they share the same set of points going along the curve. Note that rings are closed by definition, so they can have, but don't need, a repeated last point to be equal.
Calculates the ditance from the geometry g1 to the point. The distance will always be positive or zero.
The method will differ based on the type of the geometry provided: - The distance from a point to a point is just the Euclidean distance between the points. - The distance from a point to a line is the minimum distance from the point to the closest point on the given line. - The distance from a point to a linestring is the minimum distance from the point to the closest segment of the linestring. - The distance from a point to a linear ring is the minimum distance from the point to the closest segment of the linear ring. - The distance from a point to a polygon is zero if the point is within the polygon and otherwise is the minimum distance from the point to an edge of the polygon. This includes edges created by holes. - The distance from a point to a multigeometry or a geometry collection is the minimum distance between the point and any of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Calculates the signed distance from the geometry geom to the given point. Points within geom have a negative signed distance, and points outside of geom have a positive signed distance. - The signed distance from a point to a point, line, linestring, or linear ring is equal to the distance between the two. - The signed distance from a point to a polygon is negative if the point is within the polygon and is positive otherwise. The value of the distance is the minimum distance from the point to an edge of the polygon. This includes edges created by holes. - The signed distance from a point to a multigeometry or a geometry collection is the minimum signed distance between the point and any of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Returns the area of a geometry or collection of geometries. This is computed slightly differently for different geometries:
- The area of a point/multipoint is always zero.
+- The area of a curve/multicurve is always zero.
+- The area of a polygon is the absolute value of the signed area.
+- The area multi-polygon is the sum of the areas of all of the sub-polygons.
+- The area of a geometry collection, feature collection of array/iterable
+ is the sum of the areas of all of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Returns the signed area of a single geometry, based on winding order. This is computed slighly differently for different geometries:
- The signed area of a point is always zero.
+- The signed area of a curve is always zero.
+- The signed area of a polygon is computed with the shoelace formula and is
+positive if the polygon coordinates wind clockwise and negative if
+counterclockwise.
+- You cannot compute the signed area of a multipolygon as it doesn't have a
+meaning as each sub-polygon could have a different winding order.
Result will be of type T, where T is an optional argument with a default value of Float64.
Returns the angles of a geometry or collection of geometries. This is computed differently for different geometries:
- The angles of a point is an empty vector.
+- The angles of a single line segment is an empty vector.
+- The angles of a linestring or linearring is a vector of angles formed by the curve.
+- The angles of a polygin is a vector of vectors of angles formed by each ring.
+- The angles of a multi-geometry collection is a vector of the angles of each of the
+ sub-geometries as defined above.
Result will be a Vector, or nested set of vectors, of type T where an optional argument with a default value of Float64.
Recursively wrap the object with a GeoInterface.jl geometry, calculating and adding an Extents.Extent to all objects.
This can improve performance when extents need to be checked multiple times, such when needing to check if many points are in geometries, and using their extents as a quick filter for obviously exterior points.
Keywords
threaded: true or false. Whether to use multithreading. Defaults to false.
crs: The CRS to attach to geometries. Defaults to nothing.
Returns the interpolated value at point within polygon using the barycentric coordinate method method. values are the per-point values for the polygon which are to be interpolated.
Returns an object of type V.
Warning
Barycentric interpolation is currently defined only for 2-dimensional polygons. If you pass a 3-D polygon in, the Z coordinate will be used as per-vertex value to be interpolated (the M coordinate in GIS parlance).
Abstract supertype for barycentric coordinate methods. The subtypes may serve as dispatch types, or may cache some information about the target polygon.
API
The following methods must be implemented for all subtypes:
This correction ensures that the polygons included in a multipolygon aren't intersecting. If any polygon's are intersecting, they will be made nonintersecting through the difference operation to create a unique set of disjoint (other than potentially connections by a single point) polygons covering the same area. See also GeometryCorrection, UnionIntersectingPolygons.
A method for segmentizing geometries by adding extra vertices to the geometry so that no segment is longer than a given distance. This method calculates the distance between points on the geodesic, and assumes input in lat/long coordinates.
Warning
Any input geometries must be in lon/lat coordinates! If not, the method may fail or error.
Arguments
max_distance::Real: The maximum distance, in meters, between vertices in the geometry.
equatorial_radius::Real=6378137: The equatorial radius of the Earth, in meters. Passed to Proj.geod_geodesic.
flattening::Real=1/298.257223563: The flattening of the Earth, which is the ratio of the difference between the equatorial and polar radii to the equatorial radius. Passed to Proj.geod_geodesic.
One can also omit the equatorial_radius and flattening keyword arguments, and pass a geodesic object directly to the eponymous keyword.
This method uses the Proj/GeographicLib API for geodesic calculations.
This abstract type represents a geometry correction.
Interface
Any GeometryCorrection must implement two functions: * application_level(::GeometryCorrection)::AbstractGeometryTrait: This function should return the GeoInterface trait that the correction is intended to be applied to, like PointTrait or LineStringTrait or PolygonTrait. * (::GeometryCorrection)(::AbstractGeometryTrait, geometry)::(some_geometry): This function should apply the correction to the given geometry, and return a new geometry.
Enum for the orientation of a line with respect to a curve. A line can be line_cross (crossing over the curve), line_hinge (crossing the endpoint of the curve), line_over (colinear with the curve), or line_out (not interacting with the curve).
A method for segmentizing geometries by adding extra vertices to the geometry so that no segment is longer than a given distance.
Here, max_distance is a purely nondimensional quantity and will apply in the input space. This is to say, that if the polygon is provided in lat/lon coordinates then the max_distance will be in degrees of arc. If the polygon is provided in meters, then the max_distance will be in meters.
This struct holds a trait parameter or a union of trait parameters.
It is primarily used for dispatch into methods which select trait levels, like apply, or as a parameter to target.
Constructors
julia
TraitTarget(GI.PointTrait())
+TraitTarget(GI.LineStringTrait(), GI.LinearRingTrait()) # and other traits as you may like
+TraitTarget(TraitTarget(...))
+# There are also type based constructors available, but that's not advised.
+TraitTarget(GI.PointTrait)
+TraitTarget(Union{GI.LineStringTrait, GI.LinearRingTrait})
+# etc.
This correction ensures that the polygon's included in a multipolygon aren't intersecting. If any polygon's are intersecting, they will be combined through the union operation to create a unique set of disjoint (other than potentially connections by a single point) polygons covering the same area.
Two curves are equal if they share the same set of point, representing the same geometry. Both curves must must be composed of the same set of points, however, they do not have to wind in the same direction, or start on the same point to be equivalent. Inputs: c1 first geometry c2 second geometry closed_type1::Bool true if c1 is closed by definition (polygon, linear ring) closed_type2::Bool true if c2 is closed by definition (polygon, linear ring)
Returns the angles of a geometry or collection of geometries. This is computed differently for different geometries:
- The angles of a point is an empty vector.
+- The angles of a single line segment is an empty vector.
+- The angles of a linestring or linearring is a vector of angles formed by the curve.
+- The angles of a polygin is a vector of vectors of angles formed by each ring.
+- The angles of a multi-geometry collection is a vector of the angles of each of the
+ sub-geometries as defined above.
Result will be a Vector, or nested set of vectors, of type T where an optional argument with a default value of Float64.
Reconstruct a geometry, feature, feature collection, or nested vectors of either using the function f on the target trait.
f(target_geom) => x where x also has the target trait, or a trait that can be substituted. For example, swapping PolgonTrait to MultiPointTrait will fail if the outer object has MultiPolygonTrait, but should work if it has FeatureTrait.
Objects "shallower" than the target trait are always completely rebuilt, like a Vector of FeatureCollectionTrait of FeatureTrait when the target has PolygonTrait and is held in the features. These will always be GeoInterface geometries/feature/feature collections. But "deeper" objects may remain unchanged or be whatever GeoInterface compatible objects f returns.
The result is a functionally similar geometry with values depending on f.
threaded: true or false. Whether to use multithreading. Defaults to false.
crs: The CRS to attach to geometries. Defaults to nothing.
calc_extent: true or false. Whether to calculate the extent. Defaults to false.
Example
Flipped point the order in any feature or geometry, or iterables of either:
julia
import GeoInterface as GI
+import GeometryOps as GO
+geom = GI.Polygon([GI.LinearRing([(1, 2), (3, 4), (5, 6), (1, 2)]),
+ GI.LinearRing([(3, 4), (5, 6), (6, 7), (3, 4)])])
+
+flipped_geom = GO.apply(GI.PointTrait, geom) do p
+ (GI.y(p), GI.x(p))
+end
Returns the area of a geometry or collection of geometries. This is computed slightly differently for different geometries:
- The area of a point/multipoint is always zero.
+- The area of a curve/multicurve is always zero.
+- The area of a polygon is the absolute value of the signed area.
+- The area multi-polygon is the sum of the areas of all of the sub-polygons.
+- The area of a geometry collection, feature collection of array/iterable
+ is the sum of the areas of all of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Returns the interpolated value at point within polygon using the barycentric coordinate method method. values are the per-point values for the polygon which are to be interpolated.
Returns an object of type V.
Warning
Barycentric interpolation is currently defined only for 2-dimensional polygons. If you pass a 3-D polygon in, the Z coordinate will be used as per-vertex value to be interpolated (the M coordinate in GIS parlance).
Return true if the second geometry is completely contained by the first geometry. The interiors of both geometries must intersect and the interior and boundary of the secondary (g2) must not intersect the exterior of the first (g1).
contains returns the exact opposite result of within.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = GI.Point((1, 2))
+
+GO.contains(line, point)
+# output
+true
Returns the area of intersection between given geometry and grid cell defined by its minimum and maximum x and y-values. This is computed differently for different geometries:
The signed area of a point is always zero.
The signed area of a curve is always zero.
The signed area of a polygon is calculated by tracing along its edges and switching to the cell edges if needed.
The coverage of a geometry collection, multi-geometry, feature collection of array/iterable is the sum of the coverages of all of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Return true if the first geometry is completely covered by the second geometry. The interior and boundary of the primary geometry (g1) must not intersect the exterior of the secondary geometry (g2).
Furthermore, coveredby returns the exact opposite result of covers. They are equivalent with the order of the arguments swapped.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+p1 = GI.Point(0.0, 0.0)
+p2 = GI.Point(1.0, 1.0)
+l1 = GI.Line([p1, p2])
+
+GO.coveredby(p1, l1)
+# output
+true
Return true if the first geometry is completely covers the second geometry, The exterior and boundary of the second geometry must not be outside of the interior and boundary of the first geometry. However, the interiors need not intersect.
covers returns the exact opposite result of coveredby.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+l1 = GI.LineString([(1.0, 1.0), (1.0, 2.0), (1.0, 3.0), (1.0, 4.0)])
+l2 = GI.LineString([(1.0, 1.0), (1.0, 2.0)])
+
+GO.covers(l1, l2)
+# output
+true
Return true if the intersection results in a geometry whose dimension is one less than the maximum dimension of the two source geometries and the intersection set is interior to both source geometries.
TODO: broken
Examples
julia
import GeoInterface as GI, GeometryOps as GO
+# TODO: Add working example
Return given geom cut by given line as a list of geometries of the same type as the input geom. Return the original geometry as only list element if none are found. Line must cut fully through given geometry or the original geometry will be returned.
Note: This currently doesn't work for degenerate cases there line crosses through vertices.
Return the difference between two geometries as a list of geometries. Return an empty list if none are found. The type of the list will be constrained as much as possible given the input geometries. Furthermore, the user can provide a taget type as a keyword argument and a list of target geometries found in the difference will be returned. The user can also provide a float type that they would like the points of returned geometries to be. If the user is taking a intersection involving one or more multipolygons, and the multipolygon might be comprised of polygons that intersect, if fix_multipoly is set to an IntersectingPolygons correction (the default is UnionIntersectingPolygons()), then the needed multipolygons will be fixed to be valid before performing the intersection to ensure a correct answer. Only set fix_multipoly to false if you know that the multipolygons are valid, as it will avoid unneeded computation.
Calculates the ditance from the geometry g1 to the point. The distance will always be positive or zero.
The method will differ based on the type of the geometry provided: - The distance from a point to a point is just the Euclidean distance between the points. - The distance from a point to a line is the minimum distance from the point to the closest point on the given line. - The distance from a point to a linestring is the minimum distance from the point to the closest segment of the linestring. - The distance from a point to a linear ring is the minimum distance from the point to the closest segment of the linear ring. - The distance from a point to a polygon is zero if the point is within the polygon and otherwise is the minimum distance from the point to an edge of the polygon. This includes edges created by holes. - The distance from a point to a multigeometry or a geometry collection is the minimum distance between the point and any of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Recursively wrap the object with a GeoInterface.jl geometry, calculating and adding an Extents.Extent to all objects.
This can improve performance when extents need to be checked multiple times, such when needing to check if many points are in geometries, and using their extents as a quick filter for obviously exterior points.
Keywords
threaded: true or false. Whether to use multithreading. Defaults to false.
crs: The CRS to attach to geometries. Defaults to nothing.
Two linear rings are equal if they share the same set of points going along the curve. Note that rings are closed by definition, so they can have, but don't need, a repeated last point to be equal.
A linear ring and a line/linestring are equal if they share the same set of points going along the curve. Note that lines aren't closed by defintion, but rings are, so the line must have a repeated last point to be equal
A line/linestring and a linear ring are equal if they share the same set of points going along the curve. Note that lines aren't closed by defintion, but rings are, so the line must have a repeated last point to be equal
Lazily flatten any AbstractArray, iterator, FeatureCollectionTrait, FeatureTrait or AbstractGeometryTrait object obj, so that objects with the target trait are returned by the iterator.
If f is passed in it will be applied to the target geometries.
Return the intersection between two geometries as a list of geometries. Return an empty list if none are found. The type of the list will be constrained as much as possible given the input geometries. Furthermore, the user can provide a target type as a keyword argument and a list of target geometries found in the intersection will be returned. The user can also provide a float type that they would like the points of returned geometries to be. If the user is taking a intersection involving one or more multipolygons, and the multipolygon might be comprised of polygons that intersect, if fix_multipoly is set to an IntersectingPolygons correction (the default is UnionIntersectingPolygons()), then the needed multipolygons will be fixed to be valid before performing the intersection to ensure a correct answer. Only set fix_multipoly to nothing if you know that the multipolygons are valid, as it will avoid unneeded computation.
Return a list of intersection points between two geometries of type GI.Point. If no intersection point was possible given geometry extents, returns an empty list.
Compare two Geometries of the same dimension and return true if their intersection set results in a geometry different from both but of the same dimension. This means one geometry cannot be within or contain the other and they cannot be equal
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+poly1 = GI.Polygon([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+poly2 = GI.Polygon([[(1,1), (1,6), (6,6), (6,1), (1,1)]])
+
+GO.overlaps(poly1, poly2)
+# output
+true
Polygonize an AbstractMatrix of values, currently to a single class of polygons.
Returns a MultiPolygon for Bool values and f return values, and a FeatureCollection of Features holding MultiPolygon for all other values.
Function f should return either true or false or a transformation of values into simpler groups, especially useful for floating point arrays.
If xs and ys are ranges, they are used as the pixel/cell center points. If they are Vector of Tuple they are used as the lower and upper bounds of each pixel/cell.
Keywords
minpoints: ignore polygons with less than minpoints points.
values: the values to turn into polygons. By default these are union(A), If function f is passed these refer to the return values of f, by default union(map(f, A). If values Bool, false is ignored and a single MultiPolygon is returned rather than a FeatureCollection.
Example
julia
using GeometryOps
+A = rand(100, 100)
+multipolygon = polygonize(>(0.5), A);
By default geometries will be rebuilt as a GeoInterface.Wrappers geometry, but rebuild can have methods added to it to dispatch on geometries from other packages and specify how to rebuild them.
Segmentize a geometry by adding extra vertices to the geometry so that no segment is longer than a given distance. This is useful for plotting geometries with a limited number of vertices, or for ensuring that a geometry is not too "coarse" for a given application.
Arguments
method::SegmentizeMethod = LinearSegments(): The method to use for segmentizing the geometry. At the moment, only LinearSegments and GeodesicSegments are available.
geom: The geometry to segmentize. Must be a LineString, LinearRing, or greater in complexity.
max_distance::Real: The maximum distance, in the input space, between vertices in the geometry. Only used if you don't explicitly pass a method.
Returns a geometry of similar type to the input geometry, but resampled.
Returns the signed area of a single geometry, based on winding order. This is computed slighly differently for different geometries:
- The signed area of a point is always zero.
+- The signed area of a curve is always zero.
+- The signed area of a polygon is computed with the shoelace formula and is
+positive if the polygon coordinates wind clockwise and negative if
+counterclockwise.
+- You cannot compute the signed area of a multipolygon as it doesn't have a
+meaning as each sub-polygon could have a different winding order.
Result will be of type T, where T is an optional argument with a default value of Float64.
Calculates the signed distance from the geometry geom to the given point. Points within geom have a negative signed distance, and points outside of geom have a positive signed distance. - The signed distance from a point to a point, line, linestring, or linear ring is equal to the distance between the two. - The signed distance from a point to a polygon is negative if the point is within the polygon and is positive otherwise. The value of the distance is the minimum distance from the point to an edge of the polygon. This includes edges created by holes. - The signed distance from a point to a multigeometry or a geometry collection is the minimum signed distance between the point and any of the sub-geometries.
Result will be of type T, where T is an optional argument with a default value of Float64.
Return true if the first geometry touches the second geometry. In other words, the two interiors cannot interact, but one of the geometries must have a boundary point that interacts with either the other geometies interior or boundary.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+
+l1 = GI.Line([(0.0, 0.0), (1.0, 0.0)])
+l2 = GI.Line([(1.0, 1.0), (1.0, -1.0)])
+
+GO.touches(l1, l2)
+# output
+true
Return the union between two geometries as a list of geometries. Return an empty list if none are found. The type of the list will be constrained as much as possible given the input geometries. Furthermore, the user can provide a taget type as a keyword argument and a list of target geometries found in the difference will be returned. The user can also provide a float type 'T' that they would like the points of returned geometries to be. If the user is taking a intersection involving one or more multipolygons, and the multipolygon might be comprised of polygons that intersect, if fix_multipoly is set to an IntersectingPolygons correction (the default is UnionIntersectingPolygons()), then the needed multipolygons will be fixed to be valid before performing the intersection to ensure a correct answer. Only set fix_multipoly to false if you know that the multipolygons are valid, as it will avoid unneeded computation.
Return true if the first geometry is completely within the second geometry. The interiors of both geometries must intersect and the interior and boundary of the primary geometry (geom1) must not intersect the exterior of the secondary geometry (geom2).
Furthermore, within returns the exact opposite result of contains.
Examples
julia
import GeometryOps as GO, GeoInterface as GI
+
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = (1, 2)
+GO.within(point, line)
+
+# output
+true
K. Hormann and N. Sukumar. Generalized Barycentric Coordinates in Computer Graphics and Computational Mechanics. Taylor & Fancis, CRC Press, 2017. ↩︎
`,17);function m(C,f,v,T,A,G){return t(),e("div",null,[h,s("div",p,[r,a(" "),k,a(" — "),o,a(". "),d,s("mjx-container",g,[(t(),e("svg",y,c)),u]),b]),F])}const D=n(l,[["render",m]]);export{O as __pageData,D as default};
diff --git a/previews/PR149/assets/api.md.Dpn612f9.lean.js b/previews/PR149/assets/api.md.Dpn612f9.lean.js
new file mode 100644
index 000000000..8bb52b405
--- /dev/null
+++ b/previews/PR149/assets/api.md.Dpn612f9.lean.js
@@ -0,0 +1 @@
+import{_ as n,c as e,j as s,a,a6 as i,o as t}from"./chunks/framework.CDOaXZPW.js";const O=JSON.parse('{"title":"Full GeometryOps API documentation","description":"","frontmatter":{},"headers":[],"relativePath":"api.md","filePath":"api.md","lastUpdated":null}'),l={name:"api.md"},h=i("",210),p={style:{"border-width":"1px","border-style":"solid","border-color":"black",padding:"1em","border-radius":"25px"}},r=s("a",{id:"GeometryOps.t_value-Union{Tuple{T2}, Tuple{T1}, Tuple{N}, Tuple{Union{Tuple{Vararg{T1, N}}, StaticArraysCore.StaticArray{Tuple{N}, T1, 1}}, Union{Tuple{Vararg{T1, N}}, StaticArraysCore.StaticArray{Tuple{N}, T1, 1}}, T2, T2}} where {N, T1<:Real, T2<:Real}",href:"#GeometryOps.t_value-Union{Tuple{T2}, Tuple{T1}, Tuple{N}, Tuple{Union{Tuple{Vararg{T1, N}}, StaticArraysCore.StaticArray{Tuple{N}, T1, 1}}, Union{Tuple{Vararg{T1, N}}, StaticArraysCore.StaticArray{Tuple{N}, T1, 1}}, T2, T2}} where {N, T1<:Real, T2<:Real}"},"#",-1),k=s("b",null,[s("u",null,"GeometryOps.t_value")],-1),o=s("i",null,"Method",-1),d=i("",3),g={class:"MathJax",jax:"SVG",display:"true",style:{direction:"ltr",display:"block","text-align":"center",margin:"1em 0",position:"relative"}},y={style:{overflow:"visible","min-height":"1px","min-width":"1px","vertical-align":"-2.059ex"},xmlns:"http://www.w3.org/2000/svg",width:"27.746ex",height:"5.362ex",role:"img",focusable:"false",viewBox:"0 -1460 12263.9 2370","aria-hidden":"true"},E=i("",1),c=[E],u=s("mjx-assistive-mml",{unselectable:"on",display:"block",style:{top:"0px",left:"0px",clip:"rect(1px, 1px, 1px, 1px)","-webkit-touch-callout":"none","-webkit-user-select":"none","-khtml-user-select":"none","-moz-user-select":"none","-ms-user-select":"none","user-select":"none",position:"absolute",padding:"1px 0px 0px 0px",border:"0px",display:"block",overflow:"hidden",width:"100%"}},[s("math",{xmlns:"http://www.w3.org/1998/Math/MathML",display:"block"},[s("mi",null,"t"),s("mi",null,"ᵢ"),s("mo",null,"="),s("mfrac",null,[s("mrow",null,[s("mrow",{"data-mjx-texclass":"ORD"},[s("mi",{"data-mjx-auto-op":"false"},"det")]),s("mrow",{"data-mjx-texclass":"INNER"},[s("mo",{"data-mjx-texclass":"OPEN"},"("),s("mi",null,"s"),s("mi",null,"ᵢ"),s("mo",null,","),s("mi",null,"s"),s("mi",null,"ᵢ"),s("mrow",{"data-mjx-texclass":"ORD"},[s("mo",{"data-mjx-pseudoscript":"true"},"₊")]),s("mrow",{"data-mjx-texclass":"ORD"},[s("mo",{"data-mjx-pseudoscript":"true"},"₁")]),s("mo",{"data-mjx-texclass":"CLOSE"},")")])]),s("mrow",null,[s("mi",null,"r"),s("mi",null,"ᵢ"),s("mo",null,"∗"),s("mi",null,"r"),s("mi",null,"ᵢ"),s("mrow",{"data-mjx-texclass":"ORD"},[s("mo",{"data-mjx-pseudoscript":"true"},"₊")]),s("mrow",{"data-mjx-texclass":"ORD"},[s("mo",{"data-mjx-pseudoscript":"true"},"₁")]),s("mo",null,"+"),s("mi",null,"s"),s("mi",null,"ᵢ"),s("mo",null,"⋅"),s("mi",null,"s"),s("mi",null,"ᵢ"),s("mrow",{"data-mjx-texclass":"ORD"},[s("mo",{"data-mjx-pseudoscript":"true"},"₊")]),s("mrow",{"data-mjx-texclass":"ORD"},[s("mo",{"data-mjx-pseudoscript":"true"},"₁")])])])])],-1),b=i("",3),F=i("",17);function m(C,f,v,T,A,G){return t(),e("div",null,[h,s("div",p,[r,a(" "),k,a(" — "),o,a(". "),d,s("mjx-container",g,[(t(),e("svg",y,c)),u]),b]),F])}const D=n(l,[["render",m]]);export{O as __pageData,D as default};
diff --git a/previews/PR149/assets/app.D5aAhDEF.js b/previews/PR149/assets/app.D5aAhDEF.js
new file mode 100644
index 000000000..f641d36da
--- /dev/null
+++ b/previews/PR149/assets/app.D5aAhDEF.js
@@ -0,0 +1 @@
+import{U as o,a7 as p,a8 as u,a9 as l,aa as c,ab as f,ac as d,ad as m,ae as h,af as g,ag as A,d as P,u as v,y,x as w,ah as C,ai as R,aj as b,a5 as E}from"./chunks/framework.CDOaXZPW.js";import{R as S}from"./chunks/theme.DThdfNNt.js";function i(e){if(e.extends){const a=i(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const s=i(S),T=P({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=v();return y(()=>{w(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&C(),R(),b(),s.setup&&s.setup(),()=>E(s.Layout)}});async function _(){globalThis.__VITEPRESS__=!0;const e=x(),a=j();a.provide(u,e);const t=l(e.route);return a.provide(c,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),s.enhanceApp&&await s.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function j(){return h(T)}function x(){let e=o,a;return g(t=>{let n=A(t),r=null;return n&&(e&&(a=n),(e||a===n)&&(n=n.replace(/\.js$/,".lean.js")),r=import(n)),o&&(e=!1),r},s.NotFound)}o&&_().then(({app:e,router:a,data:t})=>{a.go().then(()=>{p(a.route,t.site),e.mount("#app")})});export{_ as createApp};
diff --git a/previews/PR149/assets/awkfodg.CIBNG3Jj.png b/previews/PR149/assets/awkfodg.CIBNG3Jj.png
new file mode 100644
index 000000000..bce1fbfa1
Binary files /dev/null and b/previews/PR149/assets/awkfodg.CIBNG3Jj.png differ
diff --git a/previews/PR149/assets/bbznugt.CgiryX2p.png b/previews/PR149/assets/bbznugt.CgiryX2p.png
new file mode 100644
index 000000000..dcf01fb21
Binary files /dev/null and b/previews/PR149/assets/bbznugt.CgiryX2p.png differ
diff --git a/previews/PR149/assets/bicbrwh.Dig-DWOQ.png b/previews/PR149/assets/bicbrwh.Dig-DWOQ.png
new file mode 100644
index 000000000..13977e4c3
Binary files /dev/null and b/previews/PR149/assets/bicbrwh.Dig-DWOQ.png differ
diff --git a/previews/PR149/assets/call_notes.md.sXYzUR88.js b/previews/PR149/assets/call_notes.md.sXYzUR88.js
new file mode 100644
index 000000000..32bd029eb
--- /dev/null
+++ b/previews/PR149/assets/call_notes.md.sXYzUR88.js
@@ -0,0 +1 @@
+import{_ as e,c as i,o as l,a6 as t}from"./chunks/framework.CDOaXZPW.js";const m=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"call_notes.md","filePath":"call_notes.md","lastUpdated":null}'),o={name:"call_notes.md"},a=t('
@example accurate GI.Polygon.(GO.flatten(Union{GI.LineStringTrait, GI.LinearRingTrait}, all_adm0) |> collect .|> x -> [x]) .|> GO.signed_area |> sum_kbn \`\`\`
`,16),l=[n];function h(p,k,d,r,c,g){return a(),i("div",null,l)}const u=s(e,[["render",h]]);export{o as __pageData,u as default};
diff --git a/previews/PR149/assets/experiments_accurate_accumulators.md.klTXR69a.lean.js b/previews/PR149/assets/experiments_accurate_accumulators.md.klTXR69a.lean.js
new file mode 100644
index 000000000..1159c9653
--- /dev/null
+++ b/previews/PR149/assets/experiments_accurate_accumulators.md.klTXR69a.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as t}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Accurate accumulation","description":"","frontmatter":{},"headers":[],"relativePath":"experiments/accurate_accumulators.md","filePath":"experiments/accurate_accumulators.md","lastUpdated":null}'),e={name:"experiments/accurate_accumulators.md"},n=t("",16),l=[n];function h(p,k,d,r,c,g){return a(),i("div",null,l)}const u=s(e,[["render",h]]);export{o as __pageData,u as default};
diff --git a/previews/PR149/assets/experiments_predicates.md.Mdm6NeU-.js b/previews/PR149/assets/experiments_predicates.md.Mdm6NeU-.js
new file mode 100644
index 000000000..edd91868a
--- /dev/null
+++ b/previews/PR149/assets/experiments_predicates.md.Mdm6NeU-.js
@@ -0,0 +1,98 @@
+import{_ as s,c as i,o as a,a6 as h}from"./chunks/framework.CDOaXZPW.js";const k="/GeometryOps.jl/previews/PR149/assets/lpjuviw.BVgx7YYB.png",C=JSON.parse('{"title":"Predicates","description":"","frontmatter":{},"headers":[],"relativePath":"experiments/predicates.md","filePath":"experiments/predicates.md","lastUpdated":null}'),n={name:"experiments/predicates.md"},p=h(`
`,10),l=[p];function t(E,e,r,d,g,y){return a(),i("div",null,l)}const D=s(n,[["render",t]]);export{C as __pageData,D as default};
diff --git a/previews/PR149/assets/experiments_predicates.md.Mdm6NeU-.lean.js b/previews/PR149/assets/experiments_predicates.md.Mdm6NeU-.lean.js
new file mode 100644
index 000000000..1f362a696
--- /dev/null
+++ b/previews/PR149/assets/experiments_predicates.md.Mdm6NeU-.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as h}from"./chunks/framework.CDOaXZPW.js";const k="/GeometryOps.jl/previews/PR149/assets/lpjuviw.BVgx7YYB.png",C=JSON.parse('{"title":"Predicates","description":"","frontmatter":{},"headers":[],"relativePath":"experiments/predicates.md","filePath":"experiments/predicates.md","lastUpdated":null}'),n={name:"experiments/predicates.md"},p=h("",10),l=[p];function t(E,e,r,d,g,y){return a(),i("div",null,l)}const D=s(n,[["render",t]]);export{C as __pageData,D as default};
diff --git a/previews/PR149/assets/fhcfnwd.BD0hVfse.png b/previews/PR149/assets/fhcfnwd.BD0hVfse.png
new file mode 100644
index 000000000..212d1e6a0
Binary files /dev/null and b/previews/PR149/assets/fhcfnwd.BD0hVfse.png differ
diff --git a/previews/PR149/assets/gjrlysw.BOOG5oTW.png b/previews/PR149/assets/gjrlysw.BOOG5oTW.png
new file mode 100644
index 000000000..fd0dcd164
Binary files /dev/null and b/previews/PR149/assets/gjrlysw.BOOG5oTW.png differ
diff --git a/previews/PR149/assets/hxpbxsu.BEFUMtlf.png b/previews/PR149/assets/hxpbxsu.BEFUMtlf.png
new file mode 100644
index 000000000..b400f44a5
Binary files /dev/null and b/previews/PR149/assets/hxpbxsu.BEFUMtlf.png differ
diff --git a/previews/PR149/assets/index.md.CYCEqvPe.js b/previews/PR149/assets/index.md.CYCEqvPe.js
new file mode 100644
index 000000000..a96067cbc
--- /dev/null
+++ b/previews/PR149/assets/index.md.CYCEqvPe.js
@@ -0,0 +1 @@
+import{_ as i,c as a,o,j as e,a as t}from"./chunks/framework.CDOaXZPW.js";const b=JSON.parse('{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"GeometryOps.jl","text":"","tagline":"Blazing fast geometry operations in pure Julia","image":{"src":"/logo.png","alt":"GeometryOps"},"actions":[{"theme":"brand","text":"Introduction","link":"/introduction"},{"theme":"alt","text":"View on Github","link":"https://github.com/JuliaGeo/GeometryOps.jl"},{"theme":"alt","text":"API Reference","link":"/api"}]},"features":[{"icon":"","title":"Pure Julia code","details":"Fast, understandable, extensible functions","link":"/introduction"},{"icon":"","title":"Literate programming","details":"Documented source code with examples!","link":"/source/methods/clipping/cut"},{"icon":"","title":"Full integration with GeoInterface","details":"Use any GeoInterface.jl-compatible geometry","link":"https://juliageo.org/GeoInterface.jl/stable"}]},"headers":[],"relativePath":"index.md","filePath":"index.md","lastUpdated":null}'),s={name:"index.md"},n=e("p",{style:{"margin-bottom":"2cm"}},null,-1),l=e("div",{class:"vp-doc",style:{width:"80%",margin:"auto"}},[e("h1",null," What is GeometryOps.jl? "),e("p",null,"GeometryOps.jl is a package for geometric calculations on (primarily 2D) geometries."),e("p",null,[t("The driving idea behind this package is to unify all the disparate packages for geometric calculations in Julia, and make them "),e("a",{href:"https://github.com/JuliaGeo/GeoInterface.jl",target:"_blank",rel:"noreferrer"},"GeoInterface.jl"),t("-compatible. We seem to be focusing primarily on 2/2.5D geometries for now.")]),e("p",null,"Most of the usecases are driven by GIS and similar Earth data workflows, so this might be a bit specialized towards that, but methods should always be general to any coordinate space."),e("p",null,"We welcome contributions, either as pull requests or discussion on issues!")],-1),r=[n,l];function c(d,u,h,m,g,p){return o(),a("div",null,r)}const _=i(s,[["render",c]]);export{b as __pageData,_ as default};
diff --git a/previews/PR149/assets/index.md.CYCEqvPe.lean.js b/previews/PR149/assets/index.md.CYCEqvPe.lean.js
new file mode 100644
index 000000000..a96067cbc
--- /dev/null
+++ b/previews/PR149/assets/index.md.CYCEqvPe.lean.js
@@ -0,0 +1 @@
+import{_ as i,c as a,o,j as e,a as t}from"./chunks/framework.CDOaXZPW.js";const b=JSON.parse('{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"GeometryOps.jl","text":"","tagline":"Blazing fast geometry operations in pure Julia","image":{"src":"/logo.png","alt":"GeometryOps"},"actions":[{"theme":"brand","text":"Introduction","link":"/introduction"},{"theme":"alt","text":"View on Github","link":"https://github.com/JuliaGeo/GeometryOps.jl"},{"theme":"alt","text":"API Reference","link":"/api"}]},"features":[{"icon":"","title":"Pure Julia code","details":"Fast, understandable, extensible functions","link":"/introduction"},{"icon":"","title":"Literate programming","details":"Documented source code with examples!","link":"/source/methods/clipping/cut"},{"icon":"","title":"Full integration with GeoInterface","details":"Use any GeoInterface.jl-compatible geometry","link":"https://juliageo.org/GeoInterface.jl/stable"}]},"headers":[],"relativePath":"index.md","filePath":"index.md","lastUpdated":null}'),s={name:"index.md"},n=e("p",{style:{"margin-bottom":"2cm"}},null,-1),l=e("div",{class:"vp-doc",style:{width:"80%",margin:"auto"}},[e("h1",null," What is GeometryOps.jl? "),e("p",null,"GeometryOps.jl is a package for geometric calculations on (primarily 2D) geometries."),e("p",null,[t("The driving idea behind this package is to unify all the disparate packages for geometric calculations in Julia, and make them "),e("a",{href:"https://github.com/JuliaGeo/GeoInterface.jl",target:"_blank",rel:"noreferrer"},"GeoInterface.jl"),t("-compatible. We seem to be focusing primarily on 2/2.5D geometries for now.")]),e("p",null,"Most of the usecases are driven by GIS and similar Earth data workflows, so this might be a bit specialized towards that, but methods should always be general to any coordinate space."),e("p",null,"We welcome contributions, either as pull requests or discussion on issues!")],-1),r=[n,l];function c(d,u,h,m,g,p){return o(),a("div",null,r)}const _=i(s,[["render",c]]);export{b as __pageData,_ as default};
diff --git a/previews/PR149/assets/inter-italic-cyrillic-ext.r48I6akx.woff2 b/previews/PR149/assets/inter-italic-cyrillic-ext.r48I6akx.woff2
new file mode 100644
index 000000000..b6b603d59
Binary files /dev/null and b/previews/PR149/assets/inter-italic-cyrillic-ext.r48I6akx.woff2 differ
diff --git a/previews/PR149/assets/inter-italic-cyrillic.By2_1cv3.woff2 b/previews/PR149/assets/inter-italic-cyrillic.By2_1cv3.woff2
new file mode 100644
index 000000000..def40a4f6
Binary files /dev/null and b/previews/PR149/assets/inter-italic-cyrillic.By2_1cv3.woff2 differ
diff --git a/previews/PR149/assets/inter-italic-greek-ext.1u6EdAuj.woff2 b/previews/PR149/assets/inter-italic-greek-ext.1u6EdAuj.woff2
new file mode 100644
index 000000000..e070c3d30
Binary files /dev/null and b/previews/PR149/assets/inter-italic-greek-ext.1u6EdAuj.woff2 differ
diff --git a/previews/PR149/assets/inter-italic-greek.DJ8dCoTZ.woff2 b/previews/PR149/assets/inter-italic-greek.DJ8dCoTZ.woff2
new file mode 100644
index 000000000..a3c16ca40
Binary files /dev/null and b/previews/PR149/assets/inter-italic-greek.DJ8dCoTZ.woff2 differ
diff --git a/previews/PR149/assets/inter-italic-latin-ext.CN1xVJS-.woff2 b/previews/PR149/assets/inter-italic-latin-ext.CN1xVJS-.woff2
new file mode 100644
index 000000000..2210a899e
Binary files /dev/null and b/previews/PR149/assets/inter-italic-latin-ext.CN1xVJS-.woff2 differ
diff --git a/previews/PR149/assets/inter-italic-latin.C2AdPX0b.woff2 b/previews/PR149/assets/inter-italic-latin.C2AdPX0b.woff2
new file mode 100644
index 000000000..790d62dc7
Binary files /dev/null and b/previews/PR149/assets/inter-italic-latin.C2AdPX0b.woff2 differ
diff --git a/previews/PR149/assets/inter-italic-vietnamese.BSbpV94h.woff2 b/previews/PR149/assets/inter-italic-vietnamese.BSbpV94h.woff2
new file mode 100644
index 000000000..1eec0775a
Binary files /dev/null and b/previews/PR149/assets/inter-italic-vietnamese.BSbpV94h.woff2 differ
diff --git a/previews/PR149/assets/inter-roman-cyrillic-ext.BBPuwvHQ.woff2 b/previews/PR149/assets/inter-roman-cyrillic-ext.BBPuwvHQ.woff2
new file mode 100644
index 000000000..2cfe61536
Binary files /dev/null and b/previews/PR149/assets/inter-roman-cyrillic-ext.BBPuwvHQ.woff2 differ
diff --git a/previews/PR149/assets/inter-roman-cyrillic.C5lxZ8CY.woff2 b/previews/PR149/assets/inter-roman-cyrillic.C5lxZ8CY.woff2
new file mode 100644
index 000000000..e3886dd14
Binary files /dev/null and b/previews/PR149/assets/inter-roman-cyrillic.C5lxZ8CY.woff2 differ
diff --git a/previews/PR149/assets/inter-roman-greek-ext.CqjqNYQ-.woff2 b/previews/PR149/assets/inter-roman-greek-ext.CqjqNYQ-.woff2
new file mode 100644
index 000000000..36d67487d
Binary files /dev/null and b/previews/PR149/assets/inter-roman-greek-ext.CqjqNYQ-.woff2 differ
diff --git a/previews/PR149/assets/inter-roman-greek.BBVDIX6e.woff2 b/previews/PR149/assets/inter-roman-greek.BBVDIX6e.woff2
new file mode 100644
index 000000000..2bed1e85e
Binary files /dev/null and b/previews/PR149/assets/inter-roman-greek.BBVDIX6e.woff2 differ
diff --git a/previews/PR149/assets/inter-roman-latin-ext.4ZJIpNVo.woff2 b/previews/PR149/assets/inter-roman-latin-ext.4ZJIpNVo.woff2
new file mode 100644
index 000000000..9a8d1e2b5
Binary files /dev/null and b/previews/PR149/assets/inter-roman-latin-ext.4ZJIpNVo.woff2 differ
diff --git a/previews/PR149/assets/inter-roman-latin.Di8DUHzh.woff2 b/previews/PR149/assets/inter-roman-latin.Di8DUHzh.woff2
new file mode 100644
index 000000000..07d3c53ae
Binary files /dev/null and b/previews/PR149/assets/inter-roman-latin.Di8DUHzh.woff2 differ
diff --git a/previews/PR149/assets/inter-roman-vietnamese.BjW4sHH5.woff2 b/previews/PR149/assets/inter-roman-vietnamese.BjW4sHH5.woff2
new file mode 100644
index 000000000..57bdc22ae
Binary files /dev/null and b/previews/PR149/assets/inter-roman-vietnamese.BjW4sHH5.woff2 differ
diff --git a/previews/PR149/assets/introduction.md.BLWLlAIo.js b/previews/PR149/assets/introduction.md.BLWLlAIo.js
new file mode 100644
index 000000000..a14b872dc
--- /dev/null
+++ b/previews/PR149/assets/introduction.md.BLWLlAIo.js
@@ -0,0 +1 @@
+import{_ as e,c as a,o as t,a6 as o}from"./chunks/framework.CDOaXZPW.js";const f=JSON.parse('{"title":"Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"introduction.md","filePath":"introduction.md","lastUpdated":null}'),i={name:"introduction.md"},r=o('
GeometryOps.jl is a package for geometric calculations on (primarily 2D) geometries.
The driving idea behind this package is to unify all the disparate packages for geometric calculations in Julia, and make them GeoInterface.jl-compatible. We seem to be focusing primarily on 2/2.5D geometries for now.
Most of the usecases are driven by GIS and similar Earth data workflows, so this might be a bit specialized towards that, but methods should always be general to any coordinate space.
We welcome contributions, either as pull requests or discussion on issues!
Write a comment about GeoInterface.Wrapper and why it helps in type stability to guarantee a particular return type.
',13),n=[r];function c(s,p,l,d,h,m){return t(),a("div",null,n)}const g=e(i,[["render",c]]);export{f as __pageData,g as default};
diff --git a/previews/PR149/assets/introduction.md.BLWLlAIo.lean.js b/previews/PR149/assets/introduction.md.BLWLlAIo.lean.js
new file mode 100644
index 000000000..2af9d37b3
--- /dev/null
+++ b/previews/PR149/assets/introduction.md.BLWLlAIo.lean.js
@@ -0,0 +1 @@
+import{_ as e,c as a,o as t,a6 as o}from"./chunks/framework.CDOaXZPW.js";const f=JSON.parse('{"title":"Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"introduction.md","filePath":"introduction.md","lastUpdated":null}'),i={name:"introduction.md"},r=o("",13),n=[r];function c(s,p,l,d,h,m){return t(),a("div",null,n)}const g=e(i,[["render",c]]);export{f as __pageData,g as default};
diff --git a/previews/PR149/assets/ktaliog.DeeQUply.png b/previews/PR149/assets/ktaliog.DeeQUply.png
new file mode 100644
index 000000000..8a60753d0
Binary files /dev/null and b/previews/PR149/assets/ktaliog.DeeQUply.png differ
diff --git a/previews/PR149/assets/lokajyr.DHcwB147.png b/previews/PR149/assets/lokajyr.DHcwB147.png
new file mode 100644
index 000000000..9595a3cd4
Binary files /dev/null and b/previews/PR149/assets/lokajyr.DHcwB147.png differ
diff --git a/previews/PR149/assets/lpjuviw.BVgx7YYB.png b/previews/PR149/assets/lpjuviw.BVgx7YYB.png
new file mode 100644
index 000000000..1531255da
Binary files /dev/null and b/previews/PR149/assets/lpjuviw.BVgx7YYB.png differ
diff --git a/previews/PR149/assets/luasozu.C4Hz5np8.png b/previews/PR149/assets/luasozu.C4Hz5np8.png
new file mode 100644
index 000000000..bb6ab86e0
Binary files /dev/null and b/previews/PR149/assets/luasozu.C4Hz5np8.png differ
diff --git a/previews/PR149/assets/mvimxvw.Bglvb-jp.png b/previews/PR149/assets/mvimxvw.Bglvb-jp.png
new file mode 100644
index 000000000..07de50819
Binary files /dev/null and b/previews/PR149/assets/mvimxvw.Bglvb-jp.png differ
diff --git a/previews/PR149/assets/nkraqub.BwdbZIFa.png b/previews/PR149/assets/nkraqub.BwdbZIFa.png
new file mode 100644
index 000000000..2e7e99c84
Binary files /dev/null and b/previews/PR149/assets/nkraqub.BwdbZIFa.png differ
diff --git a/previews/PR149/assets/nqatpgs.C3SxJ3x-.png b/previews/PR149/assets/nqatpgs.C3SxJ3x-.png
new file mode 100644
index 000000000..5261ec3dc
Binary files /dev/null and b/previews/PR149/assets/nqatpgs.C3SxJ3x-.png differ
diff --git a/previews/PR149/assets/ofkrynl.3UVIT8DR.png b/previews/PR149/assets/ofkrynl.3UVIT8DR.png
new file mode 100644
index 000000000..108afaca3
Binary files /dev/null and b/previews/PR149/assets/ofkrynl.3UVIT8DR.png differ
diff --git a/previews/PR149/assets/paradigms.md.bkeXuTw2.js b/previews/PR149/assets/paradigms.md.bkeXuTw2.js
new file mode 100644
index 000000000..a916a41fb
--- /dev/null
+++ b/previews/PR149/assets/paradigms.md.bkeXuTw2.js
@@ -0,0 +1 @@
+import{_ as e,c as a,o as t,a6 as o}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Paradigms","description":"","frontmatter":{},"headers":[],"relativePath":"paradigms.md","filePath":"paradigms.md","lastUpdated":null}'),i={name:"paradigms.md"},r=o('
GeometryOps exposes functions like apply and applyreduce, as well as the fix and prepare APIs, that represent paradigms of programming, by which we mean the ability to program in a certain way, and in so doing, fit neatly into the tools we've built without needing to re-implement the wheel.
Below, we'll describe some of the foundational paradigms of GeometryOps, and why you should care!
The apply function allows you to decompose a given collection of geometries down to a certain level, operate on it, and reconstruct it back to the same nested form as the original. In general, its invocation is:
julia
apply(f, trait::Trait, geom)
Functionally, it's similar to map in the way you apply it to geometries - except that you tell it at which level it should stop, by passing a trait to it.
apply will start by decomposing the geometry, feature, featurecollection, iterable, or table that you pass to it, and stop when it encounters a geometry for which GI.trait(geom) isa Trait. This encompasses unions of traits especially, but beware that any geometry which is not explicitly handled, and hits GI.PointTrait, will cause an error.
apply is unlike map in that it returns reconstructed geometries, instead of the raw output of the function. If you want a purely map-like behaviour, like calculating the length of each linestring in your feature collection, then call GO.flatten(f, trait, geom), which will decompose each geometry to the given trait and apply f to it, returning the decomposition as a flattened vector.
applyreduce is like the previous map-based approach that we mentioned, except that it reduces the result of f by op. Note that applyreduce does not guarantee associativity, so it's best to have typeof(init) == returntype(op).
The fix and prepare paradigms are different from apply, though they are built on top of it. They involve the use of structs as "actions", where a constructed object indicates an action that should be taken. A trait like interface prescribes the level (polygon, linestring, point, etc) at which each action should be applied.
In general, the idea here is to be able to invoke several actions efficiently and simultaneously, for example when correcting invalid geometries, or instantiating a Prepared geometry with several preparations (sorted edge lists, rtrees, monotone chains, etc.)
',14),s=[r];function n(d,c,p,l,h,u){return t(),a("div",null,s)}const g=e(i,[["render",n]]);export{y as __pageData,g as default};
diff --git a/previews/PR149/assets/paradigms.md.bkeXuTw2.lean.js b/previews/PR149/assets/paradigms.md.bkeXuTw2.lean.js
new file mode 100644
index 000000000..3366d87e1
--- /dev/null
+++ b/previews/PR149/assets/paradigms.md.bkeXuTw2.lean.js
@@ -0,0 +1 @@
+import{_ as e,c as a,o as t,a6 as o}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Paradigms","description":"","frontmatter":{},"headers":[],"relativePath":"paradigms.md","filePath":"paradigms.md","lastUpdated":null}'),i={name:"paradigms.md"},r=o("",14),s=[r];function n(d,c,p,l,h,u){return t(),a("div",null,s)}const g=e(i,[["render",n]]);export{y as __pageData,g as default};
diff --git a/previews/PR149/assets/peculiarities.md.B24mXKK1.js b/previews/PR149/assets/peculiarities.md.B24mXKK1.js
new file mode 100644
index 000000000..9a69f9a92
--- /dev/null
+++ b/previews/PR149/assets/peculiarities.md.B24mXKK1.js
@@ -0,0 +1 @@
+import{_ as e,c as o,o as t,a6 as a}from"./chunks/framework.CDOaXZPW.js";const m=JSON.parse('{"title":"Peculiarities","description":"","frontmatter":{},"headers":[],"relativePath":"peculiarities.md","filePath":"peculiarities.md","lastUpdated":null}'),r={name:"peculiarities.md"},i=a('
apply returns the target geometries returned by f, whatever type/package they are from, but geometries, features or feature collections that wrapped the target are replaced with GeoInterace.jl wrappers with matching GeoInterface.trait to the originals. All non-geointerface iterables become Arrays. Tables.jl compatible tables are converted either back to the original type if a Tables.materializer is defined, and if not then returned as generic NamedTuple column tables (i.e., a NamedTuple of vectors).
It is recommended for consistency that f returns GeoInterface geometries unless there is a performance/conversion overhead to doing that.
Why do you want me to provide a target in set operations?
In polygon set operations like intersection, difference, and union, many different geometry types may be obtained - depending on the relationship between the polygons. For example, when performing an union on two nonintersecting polygons, one would technically have two disjoint polygons as an output.
We use the target keyword to allow the user to control which kinds of geometry they want back. For example, setting target to PolygonTrait will cause a vector of polygons to be returned (this is the only currently supported behaviour). In future, we may implement MultiPolygonTrait or GeometryCollectionTrait targets which will return a single geometry, as LibGEOS and ArchGDAL do.
This also allows for a lot more type stability - when you ask for polygons, we won't return a geometrycollection with line segments. Especially in simulation workflows, this is excellent for simplified data processing.
These are internals and explicitly not public API, meaning they may change at any time!
When dispatch can be controlled by the value of a boolean variable, this introduces type instability. Instead of introducing type instability, we chose to encode our boolean decision variables, like threaded and calc_extent in apply, as types. This allows the compiler to reason about what will happen, and call the correct compiled method, in a stable way without worrying about
',11),n=[i];function s(l,c,d,p,h,u){return t(),o("div",null,n)}const g=e(r,[["render",s]]);export{m as __pageData,g as default};
diff --git a/previews/PR149/assets/peculiarities.md.B24mXKK1.lean.js b/previews/PR149/assets/peculiarities.md.B24mXKK1.lean.js
new file mode 100644
index 000000000..828bee555
--- /dev/null
+++ b/previews/PR149/assets/peculiarities.md.B24mXKK1.lean.js
@@ -0,0 +1 @@
+import{_ as e,c as o,o as t,a6 as a}from"./chunks/framework.CDOaXZPW.js";const m=JSON.parse('{"title":"Peculiarities","description":"","frontmatter":{},"headers":[],"relativePath":"peculiarities.md","filePath":"peculiarities.md","lastUpdated":null}'),r={name:"peculiarities.md"},i=a("",11),n=[i];function s(l,c,d,p,h,u){return t(),o("div",null,n)}const g=e(r,[["render",s]]);export{m as __pageData,g as default};
diff --git a/previews/PR149/assets/pmneflj.DiwGEg2f.png b/previews/PR149/assets/pmneflj.DiwGEg2f.png
new file mode 100644
index 000000000..b9cc2026e
Binary files /dev/null and b/previews/PR149/assets/pmneflj.DiwGEg2f.png differ
diff --git a/previews/PR149/assets/poawckn.D1sul6_F.png b/previews/PR149/assets/poawckn.D1sul6_F.png
new file mode 100644
index 000000000..b700ae602
Binary files /dev/null and b/previews/PR149/assets/poawckn.D1sul6_F.png differ
diff --git a/previews/PR149/assets/ptvygff.DQj6s62y.png b/previews/PR149/assets/ptvygff.DQj6s62y.png
new file mode 100644
index 000000000..7dee5986b
Binary files /dev/null and b/previews/PR149/assets/ptvygff.DQj6s62y.png differ
diff --git a/previews/PR149/assets/pvgzvkj.Cb0_DiYE.png b/previews/PR149/assets/pvgzvkj.Cb0_DiYE.png
new file mode 100644
index 000000000..6a6cda100
Binary files /dev/null and b/previews/PR149/assets/pvgzvkj.Cb0_DiYE.png differ
diff --git a/previews/PR149/assets/source_GeometryOps.md.BHRIFvIV.js b/previews/PR149/assets/source_GeometryOps.md.BHRIFvIV.js
new file mode 100644
index 000000000..e4212dfb0
--- /dev/null
+++ b/previews/PR149/assets/source_GeometryOps.md.BHRIFvIV.js
@@ -0,0 +1,68 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"GeometryOps.jl","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOps.md","filePath":"source/GeometryOps.md","lastUpdated":null}'),l={name:"source/GeometryOps.md"},t=n(`
Import all names from GeoInterface and Extents, so users can do GO.extent or GO.trait.
julia
for name in names(GeoInterface)
+ @eval using GeoInterface: $name
+end
+for name in names(Extents)
+ @eval using GeoInterface.Extents: $name
+end
+
+function __init__()
`,8),h=[t];function k(p,e,E,r,d,g){return a(),i("div",null,h)}const F=s(l,[["render",k]]);export{y as __pageData,F as default};
diff --git a/previews/PR149/assets/source_GeometryOps.md.BHRIFvIV.lean.js b/previews/PR149/assets/source_GeometryOps.md.BHRIFvIV.lean.js
new file mode 100644
index 000000000..623a1f430
--- /dev/null
+++ b/previews/PR149/assets/source_GeometryOps.md.BHRIFvIV.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"GeometryOps.jl","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOps.md","filePath":"source/GeometryOps.md","lastUpdated":null}'),l={name:"source/GeometryOps.md"},t=n("",8),h=[t];function k(p,e,E,r,d,g){return a(),i("div",null,h)}const F=s(l,[["render",k]]);export{y as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_angles.md.BSEApLqI.js b/previews/PR149/assets/source_methods_angles.md.BSEApLqI.js
new file mode 100644
index 000000000..979a77032
--- /dev/null
+++ b/previews/PR149/assets/source_methods_angles.md.BSEApLqI.js
@@ -0,0 +1,124 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/bicbrwh.Dig-DWOQ.png",o=JSON.parse('{"title":"Angles","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/angles.md","filePath":"source/methods/angles.md","lastUpdated":null}'),l={name:"source/methods/angles.md"},k=n(`
This is the GeoInterface-compatible implementation. First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
julia
const _ANGLE_TARGETS = TraitTarget{Union{GI.PolygonTrait,GI.AbstractCurveTrait,GI.MultiPointTrait,GI.PointTrait}}()
+
+"""
+ angles(geom, ::Type{T} = Float64)
+
+Returns the angles of a geometry or collection of geometries.
+This is computed differently for different geometries:
+
+ - The angles of a point is an empty vector.
+ - The angles of a single line segment is an empty vector.
+ - The angles of a linestring or linearring is a vector of angles formed by the curve.
+ - The angles of a polygin is a vector of vectors of angles formed by each ring.
+ - The angles of a multi-geometry collection is a vector of the angles of each of the
+ sub-geometries as defined above.
+
+Result will be a Vector, or nested set of vectors, of type T where an optional argument with
+a default value of Float64.
+"""
+function angles(geom, ::Type{T} = Float64; threaded =false) where T <: AbstractFloat
+ applyreduce(vcat, _ANGLE_TARGETS, geom; threaded, init = Vector{T}()) do g
+ _angles(T, GI.trait(g), g)
+ end
+end
Points and single line segments have no angles
julia
_angles(::Type{T}, ::Union{GI.PointTrait, GI.MultiPointTrait, GI.LineTrait}, geom) where T = T[]
+
+#= The angles of a linestring are the angles formed by the line. If the first and last point
+are not explicitly repeated, the geom is not considered closed. The angles should all be on
+one side of the line, but a particular side is not guaranteed by this function. =#
+function _angles(::Type{T}, ::GI.LineStringTrait, geom) where T
+ npoints = GI.npoint(geom)
+ first_last_equal = equals(GI.getpoint(geom, 1), GI.getpoint(geom, npoints))
+ angle_list = Vector{T}(undef, npoints - (first_last_equal ? 1 : 2))
+ _find_angles!(
+ T, angle_list, geom;
+ offset = first_last_equal, close_geom = false,
+ )
+ return angle_list
+end
+
+#= The angles of a linearring are the angles within the closed line and include the angles
+formed by connecting the first and last points of the curve. =#
+function _angles(::Type{T}, ::GI.LinearRingTrait, geom; interior = true) where T
+ npoints = GI.npoint(geom)
+ first_last_equal = equals(GI.getpoint(geom, 1), GI.getpoint(geom, npoints))
+ angle_list = Vector{T}(undef, npoints - (first_last_equal ? 1 : 0))
+ _find_angles!(
+ T, angle_list, geom;
+ offset = true, close_geom = !first_last_equal, interior = interior,
+ )
+ return angle_list
+end
+
+#= The angles of a polygon is a vector of polygon angles. Note that if there are holes
+within the polyogn, the angles will be listed after the exterior ring angles in order of the
+holes. All angles, including the hole angles, are interior angles of the polygon.=#
+function _angles(::Type{T}, ::GI.PolygonTrait, geom) where T
+ angles = _angles(T, GI.LinearRingTrait(), GI.getexterior(geom); interior = true)
+ for h in GI.gethole(geom)
+ append!(angles, _angles(T, GI.LinearRingTrait(), h; interior = false))
+ end
+ return angles
+end
Find angles of a curve and insert the values into the angle_list. If offset is true, then save space for the angle at the first vertex, as the curve is closed, at the front of angle_list. If close_geom is true, then despite the first and last point not being explicitly repeated, the curve is closed and the angle of the last point should be added to angle_list. If interior is true, then all angles will be on the same side of the line
julia
function _find_angles!(
+ ::Type{T}, angle_list, geom;
+ offset, close_geom, interior = true,
+) where T
+ local p1, prev_p1_diff, p2_p1_diff
+ local start_point, start_diff
+ local extreem_idx, extreem_x, extreem_y
+ i_offset = offset ? 1 : 0
Loop through the curve and find each of the angels
julia
for (i, p2) in enumerate(GI.getpoint(geom))
+ xp2, yp2 = GI.x(p2), GI.y(p2)
+ #= Find point with smallest x values (and smallest y in case of a tie) as this point
+ is know to be convex. =#
+ if i == 1 || (xp2 < extreem_x || (xp2 == extreem_x && yp2 < extreem_y))
+ extreem_idx = i
+ extreem_x, extreem_y = xp2, yp2
+ end
+ if i > 1
+ p2_p1_diff = (xp2 - GI.x(p1), yp2 - GI.y(p1))
+ if i == 2
+ start_point = p1
+ start_diff = p2_p1_diff
+ else
+ angle_list[i - 2 + i_offset] = _diffs_calc_angle(T, prev_p1_diff, p2_p1_diff)
+ end
+ prev_p1_diff = -1 .* p2_p1_diff
+ end
+ p1 = p2
+ end
If the last point of geometry should be the same as the first, calculate closing angle
If needed, calculate first angle corresponding to the first point
julia
if offset
+ angle_list[1] = _diffs_calc_angle(T, prev_p1_diff, start_diff)
+ end
+ #= Make sure that all of the angles are on the same side of the line and inside of the
+ closed ring if the input geometry is closed. =#
+ inside_sgn = sign(angle_list[extreem_idx]) * (interior ? 1 : -1)
+ for i in eachindex(angle_list)
+ idx_sgn = sign(angle_list[i])
+ if idx_sgn == -1
+ angle_list[i] = abs(angle_list[i])
+ end
+ if idx_sgn != inside_sgn
+ angle_list[i] = 360 - angle_list[i]
+ end
+ end
+ return
+end
Calculate the angle between two vectors defined by the previous and current Δx and Δys. Angle will have a sign corresponding to the sign of the cross product between the two vectors. All angles of one sign in a given geometry are convex, while those of the other sign are concave. However, the sign corresponding to each of these can vary based on geometry and thus you must compare to an angle that is know to be convex or concave.
`,27),t=[k];function p(e,r,E,g,d,y){return a(),i("div",null,t)}const c=s(l,[["render",p]]);export{o as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_angles.md.BSEApLqI.lean.js b/previews/PR149/assets/source_methods_angles.md.BSEApLqI.lean.js
new file mode 100644
index 000000000..3fb4ee2df
--- /dev/null
+++ b/previews/PR149/assets/source_methods_angles.md.BSEApLqI.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/bicbrwh.Dig-DWOQ.png",o=JSON.parse('{"title":"Angles","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/angles.md","filePath":"source/methods/angles.md","lastUpdated":null}'),l={name:"source/methods/angles.md"},k=n("",27),t=[k];function p(e,r,E,g,d,y){return a(),i("div",null,t)}const c=s(l,[["render",p]]);export{o as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_area.md.HnYlwd-E.js b/previews/PR149/assets/source_methods_area.md.HnYlwd-E.js
new file mode 100644
index 000000000..ffb9f9b78
--- /dev/null
+++ b/previews/PR149/assets/source_methods_area.md.HnYlwd-E.js
@@ -0,0 +1,87 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/bicbrwh.Dig-DWOQ.png",t="/GeometryOps.jl/previews/PR149/assets/xsucobl.CULn5saZ.png",c=JSON.parse('{"title":"Area and signed area","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/area.md","filePath":"source/methods/area.md","lastUpdated":null}'),e={name:"source/methods/area.md"},l=n(`
Area is the amount of space occupied by a two-dimensional figure. It is always a positive value. Signed area is simply the integral over the exterior path of a polygon, minus the sum of integrals over its interior holes. It is signed such that a clockwise path has a positive area, and a counterclockwise path has a negative area. The area is the absolute value of the signed area.
To provide an example, consider this rectangle:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+rect = GI.Polygon([[(0,0), (0,1), (1,1), (1,0), (0, 0)]])
+f, a, p = poly(collect(GI.getpoint(rect)); axis = (; aspect = DataAspect()))
This is clearly a rectangle, etc. But now let's look at how the points look:
The points are ordered in a counterclockwise fashion, which means that the signed area is negative. If we reverse the order of the points, we get a postive area.
This is the GeoInterface-compatible implementation. First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Note that area and signed area are zero for all points and curves, even if the curves are closed like with a linear ring. Also note that signed area really only makes sense for polygons, given with a multipolygon can have several polygons each with a different orientation and thus the absolute value of the signed area might not be the area. This is why signed area is only implemented for polygons.
Targets for applys functions
julia
const _AREA_TARGETS = TraitTarget{Union{GI.PolygonTrait,GI.AbstractCurveTrait,GI.MultiPointTrait,GI.PointTrait}}()
+
+"""
+ area(geom, [T = Float64])::T
+
+Returns the area of a geometry or collection of geometries.
+This is computed slightly differently for different geometries:
+
+ - The area of a point/multipoint is always zero.
+ - The area of a curve/multicurve is always zero.
+ - The area of a polygon is the absolute value of the signed area.
+ - The area multi-polygon is the sum of the areas of all of the sub-polygons.
+ - The area of a geometry collection, feature collection of array/iterable
+ is the sum of the areas of all of the sub-geometries.
+
+Result will be of type T, where T is an optional argument with a default value
+of Float64.
+"""
+function area(geom, ::Type{T} = Float64; threaded=false) where T <: AbstractFloat
+ applyreduce(+, _AREA_TARGETS, geom; threaded, init=zero(T)) do g
+ _area(T, GI.trait(g), g)
+ end
+end
+
+"""
+ signed_area(geom, [T = Float64])::T
+
+Returns the signed area of a single geometry, based on winding order.
+This is computed slighly differently for different geometries:
+
+ - The signed area of a point is always zero.
+ - The signed area of a curve is always zero.
+ - The signed area of a polygon is computed with the shoelace formula and is
+ positive if the polygon coordinates wind clockwise and negative if
+ counterclockwise.
+ - You cannot compute the signed area of a multipolygon as it doesn't have a
+ meaning as each sub-polygon could have a different winding order.
+
+Result will be of type T, where T is an optional argument with a default value
+of Float64.
+"""
+signed_area(geom, ::Type{T} = Float64) where T <: AbstractFloat =
+ _signed_area(T, GI.trait(geom), geom)
Points, MultiPoints, Curves, MultiCurves
julia
_area(::Type{T}, ::GI.AbstractGeometryTrait, geom) where T = zero(T)
+
+_signed_area(::Type{T}, ::GI.AbstractGeometryTrait, geom) where T = zero(T)
LibGEOS treats linear rings as zero area. I disagree with that but we should probably maintain compatibility...
julia
_area(::Type{T}, tr::GI.LinearRingTrait, geom) where T = 0 # could be abs(_signed_area(T, tr, geom))
+
+_signed_area(::Type{T}, ::GI.LinearRingTrait, geom) where T = 0 # could be _signed_area(T, tr, geom)
Polygons
julia
_area(::Type{T}, trait::GI.PolygonTrait, poly) where T =
+ abs(_signed_area(T, trait, poly))
+
+function _signed_area(::Type{T}, ::GI.PolygonTrait, poly) where T
+ GI.isempty(poly) && return zero(T)
+ s_area = _signed_area(T, GI.getexterior(poly))
+ area = abs(s_area)
+ area == 0 && return area
Remove hole areas from total
julia
for hole in GI.gethole(poly)
+ area -= abs(_signed_area(T, hole))
+ end
Winding of exterior ring determines sign
julia
return area * sign(s_area)
+end
One term of the shoelace area formula
julia
_area_component(p1, p2) = GI.x(p1) * GI.y(p2) - GI.y(p1) * GI.x(p2)
+
+#= Calculates the signed area of a given curve. This is equivalent to integrating
+to find the area under the curve. Even if curve isn't explicitly closed by
+repeating the first point at the end of the coordinates, curve is still assumed
+to be closed. =#
+function _signed_area(::Type{T}, geom) where T
+ area = zero(T)
+ np = GI.npoint(geom)
+ np == 0 && return area
+
+ first = true
+ local pfirst, p1
Integrate the area under the curve
julia
for p2 in GI.getpoint(geom)
Skip the first and do it later This lets us work within one iteration over geom, which means on C call when using points from external libraries.
julia
if first
+ p1 = pfirst = p2
+ first = false
+ continue
+ end
Accumulate the area into area
julia
area += _area_component(p1, p2)
+ p1 = p2
+ end
Complete the last edge. If the first and last where the same this will be zero
`,40),p=[l];function k(r,d,g,E,o,y){return a(),i("div",null,p)}const C=s(e,[["render",k]]);export{c as __pageData,C as default};
diff --git a/previews/PR149/assets/source_methods_area.md.HnYlwd-E.lean.js b/previews/PR149/assets/source_methods_area.md.HnYlwd-E.lean.js
new file mode 100644
index 000000000..9770a96cb
--- /dev/null
+++ b/previews/PR149/assets/source_methods_area.md.HnYlwd-E.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/bicbrwh.Dig-DWOQ.png",t="/GeometryOps.jl/previews/PR149/assets/xsucobl.CULn5saZ.png",c=JSON.parse('{"title":"Area and signed area","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/area.md","filePath":"source/methods/area.md","lastUpdated":null}'),e={name:"source/methods/area.md"},l=n("",40),p=[l];function k(r,d,g,E,o,y){return a(),i("div",null,p)}const C=s(e,[["render",k]]);export{c as __pageData,C as default};
diff --git a/previews/PR149/assets/source_methods_barycentric.md.C5yYmZFW.js b/previews/PR149/assets/source_methods_barycentric.md.C5yYmZFW.js
new file mode 100644
index 000000000..62c7a06fe
--- /dev/null
+++ b/previews/PR149/assets/source_methods_barycentric.md.C5yYmZFW.js
@@ -0,0 +1,415 @@
+import{_ as h,c as a,j as s,a as i,a6 as t,o as n}from"./chunks/framework.CDOaXZPW.js";const L=JSON.parse('{"title":"Barycentric coordinates","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/barycentric.md","filePath":"source/methods/barycentric.md","lastUpdated":null}'),l={name:"source/methods/barycentric.md"},p=t(`
In some cases, we actually want barycentric interpolation, and have no interest in the coordinates themselves.
However, the coordinates can be useful for debugging, and when performing 3D rendering, multiple barycentric values (depth, uv) are needed for depth buffering.
julia
const _VecTypes = Union{Tuple{Vararg{T, N}}, GeometryBasics.StaticArraysCore.StaticArray{Tuple{N}, T, 1}} where {N, T}
+
+"""
+ abstract type AbstractBarycentricCoordinateMethod
+
+Abstract supertype for barycentric coordinate methods.
+The subtypes may serve as dispatch types, or may cache
+some information about the target polygon.
+
+# API
+The following methods must be implemented for all subtypes:
+- \`barycentric_coordinates!(λs::Vector{<: Real}, method::AbstractBarycentricCoordinateMethod, exterior::Vector{<: Point{2, T1}}, point::Point{2, T2})\`
+- \`barycentric_interpolate(method::AbstractBarycentricCoordinateMethod, exterior::Vector{<: Point{2, T1}}, values::Vector{V}, point::Point{2, T2})::V\`
+- \`barycentric_interpolate(method::AbstractBarycentricCoordinateMethod, exterior::Vector{<: Point{2, T1}}, interiors::Vector{<: Vector{<: Point{2, T1}}} values::Vector{V}, point::Point{2, T2})::V\`
+The rest of the methods will be implemented in terms of these, and have efficient dispatches for broadcasting.
+"""
+abstract type AbstractBarycentricCoordinateMethod end
+
+Base.@propagate_inbounds function barycentric_coordinates!(λs::Vector{<: Real}, method::AbstractBarycentricCoordinateMethod, polypoints::AbstractVector{<: Point{N1, T1}}, point::Point{N2, T2}) where {N1, N2, T1 <: Real, T2 <: Real}
+ @boundscheck @assert length(λs) == length(polypoints)
+ @boundscheck @assert length(polypoints) >= 3
+
+ @error("Not implemented yet for method $(method).")
+end
+Base.@propagate_inbounds barycentric_coordinates!(λs::Vector{<: Real}, polypoints::AbstractVector{<: Point{N1, T1}}, point::Point{N2, T2}) where {N1, N2, T1 <: Real, T2 <: Real} = barycentric_coordinates!(λs, MeanValue(), polypoints, point)
This is the GeoInterface-compatible method.
julia
"""
+ barycentric_coordinates!(λs::Vector{<: Real}, method::AbstractBarycentricCoordinateMethod, polygon, point)
+
+Loads the barycentric coordinates of \`point\` in \`polygon\` into \`λs\` using the barycentric coordinate method \`method\`.
+
+\`λs\` must be of the length of the polygon plus its holes.
+
+!!! tip
+ Use this method to avoid excess allocations when you need to calculate barycentric coordinates for many points.
+"""
+Base.@propagate_inbounds function barycentric_coordinates!(λs::Vector{<: Real}, method::AbstractBarycentricCoordinateMethod, polygon, point)
+ @assert GeoInterface.trait(polygon) isa GeoInterface.PolygonTrait
+ @assert GeoInterface.trait(point) isa GeoInterface.PointTrait
+ passable_polygon = GeoInterface.convert(GeometryBasics, polygon)
+ @assert passable_polygon isa GeometryBasics.Polygon "The polygon was converted to a $(typeof(passable_polygon)), which is not a \`GeometryBasics.Polygon\`."
+ passable_point = GeoInterface.convert(GeometryBasics, point)
+ return barycentric_coordinates!(λs, method, passable_polygon, Point2(passable_point))
+end
+
+Base.@propagate_inbounds function barycentric_coordinates(method::AbstractBarycentricCoordinateMethod, polypoints::AbstractVector{<: Point{N1, T1}}, point::Point{N2, T2}) where {N1, N2, T1 <: Real, T2 <: Real}
+ λs = zeros(promote_type(T1, T2), length(polypoints))
+ barycentric_coordinates!(λs, method, polypoints, point)
+ return λs
+end
+Base.@propagate_inbounds barycentric_coordinates(polypoints::AbstractVector{<: Point{N1, T1}}, point::Point{N2, T2}) where {N1, N2, T1 <: Real, T2 <: Real} = barycentric_coordinates(MeanValue(), polypoints, point)
3D polygons are considered to have their vertices in the XY plane, and the Z coordinate must represent some value. This is to say that the Z coordinate is interpreted as an M coordinate.
This method is the one which supports GeoInterface.
julia
"""
+ barycentric_interpolate(method = MeanValue(), polygon, values::AbstractVector{V}, point)
+
+Returns the interpolated value at \`point\` within \`polygon\` using the barycentric coordinate method \`method\`.
+\`values\` are the per-point values for the polygon which are to be interpolated.
+
+Returns an object of type \`V\`.
+
+!!! warning
+ Barycentric interpolation is currently defined only for 2-dimensional polygons.
+ If you pass a 3-D polygon in, the Z coordinate will be used as per-vertex value to be interpolated
+ (the M coordinate in GIS parlance).
+"""
+Base.@propagate_inbounds function barycentric_interpolate(method::AbstractBarycentricCoordinateMethod, polygon, values::AbstractVector{V}, point) where V
+ @assert GeoInterface.trait(polygon) isa GeoInterface.PolygonTrait
+ @assert GeoInterface.trait(point) isa GeoInterface.PointTrait
+ passable_polygon = GeoInterface.convert(GeometryBasics, polygon)
+ @assert passable_polygon isa GeometryBasics.Polygon "The polygon was converted to a $(typeof(passable_polygon)), which is not a \`GeometryBasics.Polygon\`."
+ # first_poly_point = GeoInterface.getpoint(GeoInterface.getexterior(polygon))
+ passable_point = GeoInterface.convert(GeometryBasics, point)
+ return barycentric_interpolate(method, passable_polygon, Point2(passable_point))
+end
+Base.@propagate_inbounds barycentric_interpolate(polygon, values::AbstractVector{V}, point) where V = barycentric_interpolate(MeanValue(), polygon, values, point)
+
+"""
+ weighted_mean(weight::Real, x1, x2)
+
+Returns the weighted mean of \`x1\` and \`x2\`, where \`weight\` is the weight of \`x1\`.
+
+Specifically, calculates \`x1 * weight + x2 * (1 - weight)\`.
+
+!!! note
+ The idea for this method is that you can override this for custom types, like Color types, in extension modules.
+"""
+function weighted_mean(weight::WT, x1, x2) where {WT <: Real}
+ return muladd(x1, weight, x2 * (oneunit(WT) - weight))
+end
+
+
+"""
+ MeanValue() <: AbstractBarycentricCoordinateMethod
+
+This method calculates barycentric coordinates using the mean value method.
+
+# References
+
+"""
+struct MeanValue <: AbstractBarycentricCoordinateMethod
+end
Before we go to the actual implementation, there are some quick and simple utility functions that we need to implement. These are mainly for convenience and code brevity.
julia
"""
+ _det(s1::Point2{T1}, s2::Point2{T2}) where {T1 <: Real, T2 <: Real}
+
+Returns the determinant of the matrix formed by \`hcat\`'ing two points \`s1\` and \`s2\`.
+
+Specifically, this is:
+\`\`\`julia
+s1[1] * s2[2] - s1[2] * s2[1]
+\`\`\`
+"""
+function _det(s1::_VecTypes{2, T1}, s2::_VecTypes{2, T2}) where {T1 <: Real, T2 <: Real}
+ return s1[1] * s2[2] - s1[2] * s2[1]
+end
+
+"""
+ t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)
+
+Returns the "T-value" as described in Hormann's presentation [^HormannPresentation] on how to calculate
+the mean-value coordinate.
+
+Here, \`sᵢ\` is the vector from vertex \`vᵢ\` to the point, and \`rᵢ\` is the norm (length) of \`sᵢ\`.
+\`s\` must be \`Point\` and \`r\` must be real numbers.
+
+\`\`\`math
+tᵢ = \\\\frac{\\\\mathrm{det}\\\\left(sᵢ, sᵢ₊₁\\\\right)}{rᵢ * rᵢ₊₁ + sᵢ ⋅ sᵢ₊₁}
+\`\`\`
+
+[^HormannPresentation]: K. Hormann and N. Sukumar. Generalized Barycentric Coordinates in Computer Graphics and Computational Mechanics. Taylor & Fancis, CRC Press, 2017.
+\`\`\`
+
+"""
+function t_value(sᵢ::_VecTypes{N, T1}, sᵢ₊₁::_VecTypes{N, T1}, rᵢ::T2, rᵢ₊₁::T2) where {N, T1 <: Real, T2 <: Real}
+ return _det(sᵢ, sᵢ₊₁) / muladd(rᵢ, rᵢ₊₁, dot(sᵢ, sᵢ₊₁))
+end
+
+
+function barycentric_coordinates!(λs::Vector{<: Real}, ::MeanValue, polypoints::AbstractVector{<: Point{2, T1}}, point::Point{2, T2}) where {T1 <: Real, T2 <: Real}
+ @boundscheck @assert length(λs) == length(polypoints)
+ @boundscheck @assert length(polypoints) >= 3
+ n_points = length(polypoints)
+ # Initialize counters and register variables
+ # Points - these are actually vectors from point to vertices
+ # polypoints[i-1], polypoints[i], polypoints[i+1]
+ sᵢ₋₁ = polypoints[end] - point
+ sᵢ = polypoints[begin] - point
+ sᵢ₊₁ = polypoints[begin+1] - point
+ # radius / Euclidean distance between points.
+ rᵢ₋₁ = norm(sᵢ₋₁)
+ rᵢ = norm(sᵢ )
+ rᵢ₊₁ = norm(sᵢ₊₁)
+ # Perform the first computation explicitly, so we can cut down on
+ # a mod in the loop.
+ λs[1] = (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ # Loop through the rest of the vertices, compute, store in λs
+ for i in 2:n_points
+ # Increment counters + set variables
+ sᵢ₋₁ = sᵢ
+ sᵢ = sᵢ₊₁
+ sᵢ₊₁ = polypoints[mod1(i+1, n_points)] - point
+ rᵢ₋₁ = rᵢ
+ rᵢ = rᵢ₊₁
+ rᵢ₊₁ = norm(sᵢ₊₁) # radius / Euclidean distance between points.
+ λs[i] = (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ end
+ # Normalize λs to the 1-norm (sum=1)
+ λs ./= sum(λs)
+ return λs
+end
julia
function barycentric_coordinates(::MeanValue, polypoints::NTuple{N, Point{2, T2}}, point::Point{2, T1},) where {N, T1, T2}
+ ## Initialize counters and register variables
+ ## Points - these are actually vectors from point to vertices
+ ## polypoints[i-1], polypoints[i], polypoints[i+1]
+ sᵢ₋₁ = polypoints[end] - point
+ sᵢ = polypoints[begin] - point
+ sᵢ₊₁ = polypoints[begin+1] - point
+ ## radius / Euclidean distance between points.
+ rᵢ₋₁ = norm(sᵢ₋₁)
+ rᵢ = norm(sᵢ )
+ rᵢ₊₁ = norm(sᵢ₊₁)
+ λ₁ = (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ λs = ntuple(N) do i
+ if i == 1
+ return λ₁
+ end
+ ## Increment counters + set variables
+ sᵢ₋₁ = sᵢ
+ sᵢ = sᵢ₊₁
+ sᵢ₊₁ = polypoints[mod1(i+1, N)] - point
+ rᵢ₋₁ = rᵢ
+ rᵢ = rᵢ₊₁
+ rᵢ₊₁ = norm(sᵢ₊₁) # radius / Euclidean distance between points.
+ return (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ end
+
+ ∑λ = sum(λs)
+
+ return ntuple(N) do i
+ λs[i] / ∑λ
+ end
+end
This performs an inplace accumulation, using less memory and is faster. That's particularly good if you are using a polygon with a large number of points...
julia
function barycentric_interpolate(::MeanValue, polypoints::AbstractVector{<: Point{2, T1}}, values::AbstractVector{V}, point::Point{2, T2}) where {T1 <: Real, T2 <: Real, V}
+ @boundscheck @assert length(values) == length(polypoints)
+ @boundscheck @assert length(polypoints) >= 3
+
+ n_points = length(polypoints)
+ # Initialize counters and register variables
+ # Points - these are actually vectors from point to vertices
+ # polypoints[i-1], polypoints[i], polypoints[i+1]
+ sᵢ₋₁ = polypoints[end] - point
+ sᵢ = polypoints[begin] - point
+ sᵢ₊₁ = polypoints[begin+1] - point
+ # radius / Euclidean distance between points.
+ rᵢ₋₁ = norm(sᵢ₋₁)
+ rᵢ = norm(sᵢ )
+ rᵢ₊₁ = norm(sᵢ₊₁)
+ # Now, we set the interpolated value to the first point's value, multiplied
+ # by the weight computed relative to the first point in the polygon.
+ wᵢ = (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ wₜₒₜ = wᵢ
+ interpolated_value = values[begin] * wᵢ
+ for i in 2:n_points
+ # Increment counters + set variables
+ sᵢ₋₁ = sᵢ
+ sᵢ = sᵢ₊₁
+ sᵢ₊₁ = polypoints[mod1(i+1, n_points)] - point
+ rᵢ₋₁ = rᵢ
+ rᵢ = rᵢ₊₁
+ rᵢ₊₁ = norm(sᵢ₊₁)
+ # Now, we calculate the weight:
+ wᵢ = (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ # perform a weighted sum with the interpolated value:
+ interpolated_value += values[i] * wᵢ
+ # and add the weight to the total weight accumulator.
+ wₜₒₜ += wᵢ
+ end
+ # Return the normalized interpolated value.
+ return interpolated_value / wₜₒₜ
+end
When you have holes, then you have to be careful about the order you iterate around points.
Specifically, you have to iterate around each linear ring separately and ensure there are no degenerate/repeated points at the start and end!
`,34);function w(x,f,V,P,M,q){return n(),a("div",null,[p,s("p",null,[i("In the case of a triangle, barycentric coordinates are a set of three numbers "),s("mjx-container",k,[(n(),a("svg",e,E)),d]),i(", each associated with a vertex of the triangle. Any point within the triangle can be expressed as a weighted average of the vertices, where the weights are the barycentric coordinates. The weights sum to 1, and each is non-negative.")]),s("p",null,[i("For a polygon with "),s("mjx-container",g,[(n(),a("svg",y,F)),c]),i(" vertices, generalized barycentric coordinates are a set of "),s("mjx-container",C,[(n(),a("svg",A,D)),B]),i(" numbers "),s("mjx-container",T,[(n(),a("svg",m,Q)),_]),i(", each associated with a vertex of the polygon. Any point within the polygon can be expressed as a weighted average of the vertices, where the weights are the generalized barycentric coordinates.")]),v])}const R=h(l,[["render",w]]);export{L as __pageData,R as default};
diff --git a/previews/PR149/assets/source_methods_barycentric.md.C5yYmZFW.lean.js b/previews/PR149/assets/source_methods_barycentric.md.C5yYmZFW.lean.js
new file mode 100644
index 000000000..cb09237d2
--- /dev/null
+++ b/previews/PR149/assets/source_methods_barycentric.md.C5yYmZFW.lean.js
@@ -0,0 +1 @@
+import{_ as h,c as a,j as s,a as i,a6 as t,o as n}from"./chunks/framework.CDOaXZPW.js";const L=JSON.parse('{"title":"Barycentric coordinates","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/barycentric.md","filePath":"source/methods/barycentric.md","lastUpdated":null}'),l={name:"source/methods/barycentric.md"},p=t("",4),k={class:"MathJax",jax:"SVG",style:{direction:"ltr",position:"relative"}},e={style:{overflow:"visible","min-height":"1px","min-width":"1px","vertical-align":"-0.566ex"},xmlns:"http://www.w3.org/2000/svg",width:"10.692ex",height:"2.262ex",role:"img",focusable:"false",viewBox:"0 -750 4726 1000","aria-hidden":"true"},r=t("",1),E=[r],d=s("mjx-assistive-mml",{unselectable:"on",display:"inline",style:{top:"0px",left:"0px",clip:"rect(1px, 1px, 1px, 1px)","-webkit-touch-callout":"none","-webkit-user-select":"none","-khtml-user-select":"none","-moz-user-select":"none","-ms-user-select":"none","user-select":"none",position:"absolute",padding:"1px 0px 0px 0px",border:"0px",display:"block",width:"auto",overflow:"hidden"}},[s("math",{xmlns:"http://www.w3.org/1998/Math/MathML"},[s("mo",{stretchy:"false"},"("),s("msub",null,[s("mi",null,"λ"),s("mn",null,"1")]),s("mo",null,","),s("msub",null,[s("mi",null,"λ"),s("mn",null,"2")]),s("mo",null,","),s("msub",null,[s("mi",null,"λ"),s("mn",null,"3")]),s("mo",{stretchy:"false"},")")])],-1),g={class:"MathJax",jax:"SVG",style:{direction:"ltr",position:"relative"}},y={style:{overflow:"visible","min-height":"1px","min-width":"1px","vertical-align":"-0.025ex"},xmlns:"http://www.w3.org/2000/svg",width:"1.357ex",height:"1.025ex",role:"img",focusable:"false",viewBox:"0 -442 600 453","aria-hidden":"true"},o=s("g",{stroke:"currentColor",fill:"currentColor","stroke-width":"0",transform:"scale(1,-1)"},[s("g",{"data-mml-node":"math"},[s("g",{"data-mml-node":"mi"},[s("path",{"data-c":"1D45B",d:"M21 287Q22 293 24 303T36 341T56 388T89 425T135 442Q171 442 195 424T225 390T231 369Q231 367 232 367L243 378Q304 442 382 442Q436 442 469 415T503 336T465 179T427 52Q427 26 444 26Q450 26 453 27Q482 32 505 65T540 145Q542 153 560 153Q580 153 580 145Q580 144 576 130Q568 101 554 73T508 17T439 -10Q392 -10 371 17T350 73Q350 92 386 193T423 345Q423 404 379 404H374Q288 404 229 303L222 291L189 157Q156 26 151 16Q138 -11 108 -11Q95 -11 87 -5T76 7T74 17Q74 30 112 180T152 343Q153 348 153 366Q153 405 129 405Q91 405 66 305Q60 285 60 284Q58 278 41 278H27Q21 284 21 287Z",style:{"stroke-width":"3"}})])])],-1),F=[o],c=s("mjx-assistive-mml",{unselectable:"on",display:"inline",style:{top:"0px",left:"0px",clip:"rect(1px, 1px, 1px, 1px)","-webkit-touch-callout":"none","-webkit-user-select":"none","-khtml-user-select":"none","-moz-user-select":"none","-ms-user-select":"none","user-select":"none",position:"absolute",padding:"1px 0px 0px 0px",border:"0px",display:"block",width:"auto",overflow:"hidden"}},[s("math",{xmlns:"http://www.w3.org/1998/Math/MathML"},[s("mi",null,"n")])],-1),C={class:"MathJax",jax:"SVG",style:{direction:"ltr",position:"relative"}},A={style:{overflow:"visible","min-height":"1px","min-width":"1px","vertical-align":"-0.025ex"},xmlns:"http://www.w3.org/2000/svg",width:"1.357ex",height:"1.025ex",role:"img",focusable:"false",viewBox:"0 -442 600 453","aria-hidden":"true"},u=s("g",{stroke:"currentColor",fill:"currentColor","stroke-width":"0",transform:"scale(1,-1)"},[s("g",{"data-mml-node":"math"},[s("g",{"data-mml-node":"mi"},[s("path",{"data-c":"1D45B",d:"M21 287Q22 293 24 303T36 341T56 388T89 425T135 442Q171 442 195 424T225 390T231 369Q231 367 232 367L243 378Q304 442 382 442Q436 442 469 415T503 336T465 179T427 52Q427 26 444 26Q450 26 453 27Q482 32 505 65T540 145Q542 153 560 153Q580 153 580 145Q580 144 576 130Q568 101 554 73T508 17T439 -10Q392 -10 371 17T350 73Q350 92 386 193T423 345Q423 404 379 404H374Q288 404 229 303L222 291L189 157Q156 26 151 16Q138 -11 108 -11Q95 -11 87 -5T76 7T74 17Q74 30 112 180T152 343Q153 348 153 366Q153 405 129 405Q91 405 66 305Q60 285 60 284Q58 278 41 278H27Q21 284 21 287Z",style:{"stroke-width":"3"}})])])],-1),D=[u],B=s("mjx-assistive-mml",{unselectable:"on",display:"inline",style:{top:"0px",left:"0px",clip:"rect(1px, 1px, 1px, 1px)","-webkit-touch-callout":"none","-webkit-user-select":"none","-khtml-user-select":"none","-moz-user-select":"none","-ms-user-select":"none","user-select":"none",position:"absolute",padding:"1px 0px 0px 0px",border:"0px",display:"block",width:"auto",overflow:"hidden"}},[s("math",{xmlns:"http://www.w3.org/1998/Math/MathML"},[s("mi",null,"n")])],-1),T={class:"MathJax",jax:"SVG",style:{direction:"ltr",position:"relative"}},m={style:{overflow:"visible","min-height":"1px","min-width":"1px","vertical-align":"-0.566ex"},xmlns:"http://www.w3.org/2000/svg",width:"14.876ex",height:"2.262ex",role:"img",focusable:"false",viewBox:"0 -750 6575.4 1000","aria-hidden":"true"},b=t("",1),Q=[b],_=s("mjx-assistive-mml",{unselectable:"on",display:"inline",style:{top:"0px",left:"0px",clip:"rect(1px, 1px, 1px, 1px)","-webkit-touch-callout":"none","-webkit-user-select":"none","-khtml-user-select":"none","-moz-user-select":"none","-ms-user-select":"none","user-select":"none",position:"absolute",padding:"1px 0px 0px 0px",border:"0px",display:"block",width:"auto",overflow:"hidden"}},[s("math",{xmlns:"http://www.w3.org/1998/Math/MathML"},[s("mo",{stretchy:"false"},"("),s("msub",null,[s("mi",null,"λ"),s("mn",null,"1")]),s("mo",null,","),s("msub",null,[s("mi",null,"λ"),s("mn",null,"2")]),s("mo",null,","),s("mo",null,"."),s("mo",null,"."),s("mo",null,"."),s("mo",null,","),s("msub",null,[s("mi",null,"λ"),s("mi",null,"n")]),s("mo",{stretchy:"false"},")")])],-1),v=t("",34);function w(x,f,V,P,M,q){return n(),a("div",null,[p,s("p",null,[i("In the case of a triangle, barycentric coordinates are a set of three numbers "),s("mjx-container",k,[(n(),a("svg",e,E)),d]),i(", each associated with a vertex of the triangle. Any point within the triangle can be expressed as a weighted average of the vertices, where the weights are the barycentric coordinates. The weights sum to 1, and each is non-negative.")]),s("p",null,[i("For a polygon with "),s("mjx-container",g,[(n(),a("svg",y,F)),c]),i(" vertices, generalized barycentric coordinates are a set of "),s("mjx-container",C,[(n(),a("svg",A,D)),B]),i(" numbers "),s("mjx-container",T,[(n(),a("svg",m,Q)),_]),i(", each associated with a vertex of the polygon. Any point within the polygon can be expressed as a weighted average of the vertices, where the weights are the generalized barycentric coordinates.")]),v])}const R=h(l,[["render",w]]);export{L as __pageData,R as default};
diff --git a/previews/PR149/assets/source_methods_centroid.md.CUsQj_QT.js b/previews/PR149/assets/source_methods_centroid.md.CUsQj_QT.js
new file mode 100644
index 000000000..acdd42fe3
--- /dev/null
+++ b/previews/PR149/assets/source_methods_centroid.md.CUsQj_QT.js
@@ -0,0 +1,93 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/fhcfnwd.BD0hVfse.png",t="/GeometryOps.jl/previews/PR149/assets/lokajyr.DHcwB147.png",F=JSON.parse('{"title":"Centroid","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/centroid.md","filePath":"source/methods/centroid.md","lastUpdated":null}'),k={name:"source/methods/centroid.md"},l=n(`
The centroid is the geometric center of a line string or area(s). Note that the centroid does not need to be inside of a concave area.
Further note that by convention a line, or linear ring, is calculated by weighting the line segments by their length, while polygons and multipolygon centroids are calculated by weighting edge's by their 'area components'.
To provide an example, consider this concave polygon in the shape of a 'C':
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+cshape = GI.Polygon([[(0,0), (0,3), (3,3), (3,2), (1,2), (1,1), (3,1), (3,0), (0,0)]])
+f, a, p = poly(collect(GI.getpoint(cshape)); axis = (; aspect = DataAspect()))
Let's see what the centroid looks like (plotted in red):
julia
cent = GO.centroid(cshape)
+scatter!(GI.x(cent), GI.y(cent), color = :red)
+f
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Note that if you call centroid on a LineString or LinearRing, the centroid_and_length function will be called due to the weighting scheme described above, while centroid_and_area is called for polygons and multipolygons. However, centroid_and_area can still be called on a LineString or LinearRing when they are closed, for example as the interior hole of a polygon.
The helper functions centroid_and_length and centroid_and_area are made availible just in case the user also needs the area or length to decrease repeat computation.
julia
"""
+ centroid(geom, [T=Float64])::Tuple{T, T}
+
+Returns the centroid of a given line segment, linear ring, polygon, or
+mutlipolygon.
+"""
+centroid(geom, ::Type{T} = Float64; threaded=false) where T =
+ centroid(GI.trait(geom), geom, T; threaded)
+function centroid(
+ trait::Union{GI.LineStringTrait, GI.LinearRingTrait}, geom, ::Type{T}=Float64; threaded=false
+) where T
+ centroid_and_length(trait, geom, T)[1]
+end
+centroid(trait, geom, ::Type{T}; threaded=false) where T =
+ centroid_and_area(geom, T; threaded)[1]
+
+"""
+ centroid_and_length(geom, [T=Float64])::(::Tuple{T, T}, ::Real)
+
+Returns the centroid and length of a given line/ring. Note this is only valid
+for line strings and linear rings.
+"""
+centroid_and_length(geom, ::Type{T}=Float64) where T =
+ centroid_and_length(GI.trait(geom), geom, T)
+function centroid_and_length(
+ ::Union{GI.LineStringTrait, GI.LinearRingTrait}, geom, ::Type{T},
+) where T
xcentroid -= xinterior * interior_area
+ ycentroid -= yinterior * interior_area
+ end
+ xcentroid /= area
+ ycentroid /= area
+ return (xcentroid, ycentroid), area
+end
The op argument for _applyreduce and point / area It combines two (point, area) tuples into one, taking the average of the centroid points weighted by the area of the geom they are from.
julia
function _combine_centroid_and_area(((x1, y1), area1), ((x2, y2), area2))
+ area = area1 + area2
+ x = (x1 * area1 + x2 * area2) / area
+ y = (y1 * area1 + y2 * area2) / area
+ return (x, y), area
+end
`,57),p=[l];function e(r,E,d,g,y,o){return a(),i("div",null,p)}const C=s(k,[["render",e]]);export{F as __pageData,C as default};
diff --git a/previews/PR149/assets/source_methods_centroid.md.CUsQj_QT.lean.js b/previews/PR149/assets/source_methods_centroid.md.CUsQj_QT.lean.js
new file mode 100644
index 000000000..8f24c0951
--- /dev/null
+++ b/previews/PR149/assets/source_methods_centroid.md.CUsQj_QT.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/fhcfnwd.BD0hVfse.png",t="/GeometryOps.jl/previews/PR149/assets/lokajyr.DHcwB147.png",F=JSON.parse('{"title":"Centroid","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/centroid.md","filePath":"source/methods/centroid.md","lastUpdated":null}'),k={name:"source/methods/centroid.md"},l=n("",57),p=[l];function e(r,E,d,g,y,o){return a(),i("div",null,p)}const C=s(k,[["render",e]]);export{F as __pageData,C as default};
diff --git a/previews/PR149/assets/source_methods_clipping_clipping_processor.md.CZ0elAO_.js b/previews/PR149/assets/source_methods_clipping_clipping_processor.md.CZ0elAO_.js
new file mode 100644
index 000000000..05d3a9cfa
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_clipping_processor.md.CZ0elAO_.js
@@ -0,0 +1,507 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Polygon clipping helpers","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/clipping_processor.md","filePath":"source/methods/clipping/clipping_processor.md","lastUpdated":null}'),h={name:"source/methods/clipping/clipping_processor.md"},t=n(`
This file contains the shared helper functions for the polygon clipping functionalities.
This enum defines which side of an edge a point is on
julia
@enum PointEdgeSide left=1 right=2 unknown=3
Constants assigned for readability
julia
const enter, exit = true, false
+const crossing, bouncing = true, false
+
+#= A point can either be the start or end of an overlapping chain of points between two
+polygons, or not an endpoint of a chain. =#
+@enum EndPointType start_chain=1 end_chain=2 not_endpoint=3
+
+#= This is the struct that makes up a_list and b_list. Many values are only used if point is
+an intersection point (ipt). =#
+@kwdef struct PolyNode{T <: AbstractFloat}
+ point::Tuple{T,T} # (x, y) values of given point
+ inter::Bool = false # If ipt, true, else 0
+ neighbor::Int = 0 # If ipt, index of equivalent point in a_list or b_list, else 0
+ idx::Int = 0 # If crossing point, index within sorted a_idx_list
+ ent_exit::Bool = false # If ipt, true if enter and false if exit, else false
+ crossing::Bool = false # If ipt, true if intersection crosses from out/in polygon, else false
+ endpoint::EndPointType = not_endpoint # If ipt, denotes if point is the start or end of an overlapping chain
+ fracs::Tuple{T,T} = (0., 0.) # If ipt, fractions along edges to ipt (a_frac, b_frac), else (0, 0)
+end
+
+#= Create a new node with all of the same field values as the given PolyNode unless
+alternative values are provided, in which case those should be used. =#
+PolyNode(node::PolyNode{T};
+ point = node.point, inter = node.inter, neighbor = node.neighbor, idx = node.idx,
+ ent_exit = node.ent_exit, crossing = node.crossing, endpoint = node.endpoint,
+ fracs = node.fracs,
+) where T = PolyNode{T}(;
+ point = point, inter = inter, neighbor = neighbor, idx = idx, ent_exit = ent_exit,
+ crossing = crossing, endpoint = endpoint, fracs = fracs)
Checks equality of two PolyNodes by backing point value, fractional value, and intersection status
This function takes in two polygon rings and calls '_build_a_list', '_build_b_list', and '_flag_ent_exit' in order to fully form a_list and b_list. The 'a_list' and 'b_list' that it returns are the fully updated vectors of PolyNodes that represent the rings 'poly_a' and 'poly_b', respectively. This function also returns 'a_idx_list', which at its "ith" index stores the index in 'a_list' at which the "ith" intersection point lies.
julia
function _build_ab_list(::Type{T}, poly_a, poly_b, delay_cross_f::F1, delay_bounce_f::F2; exact) where {T, F1, F2}
This function take in two polygon rings and creates a vector of PolyNodes to represent poly_a, including its intersection points with poly_b. The information stored in each PolyNode is needed for clipping using the Greiner-Hormann clipping algorithm.
Note: After calling this function, a_list is not fully formed because the neighboring indicies of the intersection points in b_list still need to be updated. Also we still have not update the entry and exit flags for a_list.
The a_idx_list is a list of the indicies of intersection points in a_list. The value at index i of a_idx_list is the location in a_list where the ith intersection point lies.
julia
function _build_a_list(::Type{T}, poly_a, poly_b; exact) where T
+ n_a_edges = _nedge(poly_a)
+ a_list = PolyNode{T}[] # list of points in poly_a
+ sizehint!(a_list, n_a_edges)
+ a_idx_list = Vector{Int}() # finds indices of intersection points in a_list
+ a_count = 0 # number of points added to a_list
+ n_b_intrs = 0
Loop through points of poly_a
julia
local a_pt1
+ for (i, a_p2) in enumerate(GI.getpoint(poly_a))
+ a_pt2 = (T(GI.x(a_p2)), T(GI.y(a_p2)))
+ if i <= 1 || (a_pt1 == a_pt2) # don't repeat points
+ a_pt1 = a_pt2
+ continue
+ end
Add the first point of the edge to the list of points in a_list
This function takes in the a_list and a_idx_list build in _build_a_list and poly_b and creates a vector of PolyNodes to represent poly_b. The information stored in each PolyNode is needed for clipping using the Greiner-Hormann clipping algorithm.
Note: after calling this function, b_list is not fully updated. The entry/exit flags still need to be updated. However, the neightbor value in a_list is now updated.
julia
function _build_b_list(::Type{T}, a_idx_list, a_list, n_b_intrs, poly_b) where T
Sort intersection points by insertion order in b_list
julia
sort!(a_idx_list, by = x-> a_list[x].neighbor + a_list[x].fracs[2])
Loop over points in poly_b and add each point and intersection point
julia
local b_pt1
+ for (i, b_p2) in enumerate(GI.getpoint(poly_b))
+ b_pt2 = _tuple_point(b_p2, T)
+ if i ≤ 1 || (b_pt1 == b_pt2) # don't repeat points
+ b_pt1 = b_pt2
+ continue
+ end
+ b_count += 1
+ push!(b_list, PolyNode{T}(; point = b_pt1))
+ if intr_curr ≤ n_intr_pts
+ curr_idx = a_idx_list[intr_curr]
+ curr_node = a_list[curr_idx]
+ prev_counter = b_count
+ while curr_node.neighbor == i - 1 # Add all intersection points on current edge
+ b_idx = 0
+ new_intr = PolyNode(curr_node; neighbor = curr_idx)
+ if curr_node.fracs[2] == 0 # if curr_node is segment start point
intersection point is vertex of b
julia
b_idx = prev_counter
+ b_list[b_idx] = new_intr
+ else
+ b_count += 1
+ b_idx = b_count
+ push!(b_list, new_intr)
+ end
+ a_list[curr_idx] = PolyNode(curr_node; neighbor = b_idx)
+ intr_curr += 1
+ intr_curr > n_intr_pts && break
+ curr_idx = a_idx_list[intr_curr]
+ curr_node = a_list[curr_idx]
+ end
+ end
+ b_pt1 = b_pt2
+ end
+ sort!(a_idx_list) # return a_idx_list to order of points in a_list
+ return b_list
+end
_classify_crossing!(T, poly_b, a_list; exact)
This function marks all intersection points as either bouncing or crossing points. "Delayed" crossing or bouncing intersections (a chain of edges where the central edges overlap and thus only the first and last edge of the chain determine if the chain is bounding or crossing) are marked as follows: the first and the last points are marked as crossing if the chain is crossing and delayed otherwise and all middle points are marked as bouncing. Additionally, the start and end points of the chain are marked as endpoints using the endpoints field.
julia
function _classify_crossing!(::Type{T}, a_list, b_list; exact) where T
+ napts = length(a_list)
+ nbpts = length(b_list)
_is_vertex(pt) = !pt.inter || pt.fracs[1] == 0 || pt.fracs[1] == 1 || pt.fracs[2] == 0 || pt.fracs[2] == 1
+
+#= Determines which side (right or left) of the segment a_prev-curr_pt-a_next the points
+b_prev and b_next are on. Given this is only called when curr_pt is an intersection point
+that wasn't initially classified as crossing, we know that curr_pt is either from a hinge or
+overlapping intersection and thus is an original vertex of either poly_a or poly_b. Due to
+floating point error when calculating new intersection points, we only want to use original
+vertices to determine orientation. Thus, for other points, find nearest point that is a
+vertex. Given other intersection points will be collinear along existing segments, this
+won't change the orientation. =#
+function _get_sides(b_prev, b_next, a_prev, curr_pt, a_next, i, j, a_list, b_list; exact)
+ b_prev_pt = if _is_vertex(b_prev)
+ b_prev.point
+ else # Find original start point of segment formed by b_prev and curr_pt
+ prev_idx = findprev(_is_vertex, b_list, j - 1)
+ prev_idx = isnothing(prev_idx) ? findlast(_is_vertex, b_list) : prev_idx
+ b_list[prev_idx].point
+ end
+ b_next_pt = if _is_vertex(b_next)
+ b_next.point
+ else # Find original end point of segment formed by curr_pt and b_next
+ next_idx = findnext(_is_vertex, b_list, j + 1)
+ next_idx = isnothing(next_idx) ? findfirst(_is_vertex, b_list) : next_idx
+ b_list[next_idx].point
+ end
+ a_prev_pt = if _is_vertex(a_prev)
+ a_prev.point
+ else # Find original start point of segment formed by a_prev and curr_pt
+ prev_idx = findprev(_is_vertex, a_list, i - 1)
+ prev_idx = isnothing(prev_idx) ? findlast(_is_vertex, a_list) : prev_idx
+ a_list[prev_idx].point
+ end
+ a_next_pt = if _is_vertex(a_next)
+ a_next.point
+ else # Find original end point of segment formed by curr_pt and a_next
+ next_idx = findnext(_is_vertex, a_list, i + 1)
+ next_idx = isnothing(next_idx) ? findfirst(_is_vertex, a_list) : next_idx
+ a_list[next_idx].point
+ end
Determines if Q lies to the left or right of the line formed by P1-P2-P3
julia
function _get_side(Q, P1, P2, P3; exact)
+ s1 = Predicates.orient(Q, P1, P2; exact)
+ s2 = Predicates.orient(Q, P2, P3; exact)
+ s3 = Predicates.orient(P1, P2, P3; exact)
+
+ side = if s3 ≥ 0
+ (s1 < 0) || (s2 < 0) ? right : left
+ else # s3 < 0
+ (s1 > 0) || (s2 > 0) ? left : right
+ end
+ return side
+end
+
+#= Given a list of PolyNodes, find the first element that isn't an intersection point. Then,
+test if this element is in or out of the given polygon. Return the next index, as well as
+the enter/exit status of the next intersection point (the opposite of the in/out check). If
+all points are intersection points, find the first element that either is the end of a chain
+or a crossing point that isn't in a chain. Then take the midpoint of this point and the next
+point in the list and perform the in/out check. If none of these points exist, return
+a \`next_idx\` of \`nothing\`. =#
+function _pt_off_edge_status(::Type{T}, pt_list, poly, npts; exact) where T
+ start_idx, is_non_intr_pt = findfirst(_is_not_intr, pt_list), true
+ if isnothing(start_idx)
+ start_idx, is_non_intr_pt = findfirst(_next_edge_off, pt_list), false
+ isnothing(start_idx) && return (start_idx, false)
+ end
+ next_idx = start_idx < npts ? (start_idx + 1) : 1
+ start_pt = if is_non_intr_pt
+ pt_list[start_idx].point
+ else
+ (pt_list[start_idx].point .+ pt_list[next_idx].point) ./ 2
+ end
+ start_status = !_point_filled_curve_orientation(start_pt, poly; in = true, on = false, out = false, exact)
+ return next_idx, start_status
+end
Check if a PolyNode is an intersection point
julia
_is_not_intr(pt) = !pt.inter
+#= Check if a PolyNode is the last point of a chain or a non-overlapping crossing point.
+The next midpoint of one of these points and the next point within a polygon must not be on
+the polygon edge. =#
+_next_edge_off(pt) = (pt.endpoint == end_chain) || (pt.crossing && pt.endpoint == not_endpoint)
This function flags all the intersection points as either an 'entry' or 'exit' point in relation to the given polygon. For non-delayed crossings we simply alternate the enter/exit status. This also holds true for the first and last points of a delayed bouncing, where they both have an opposite entry/exit flag. Conversely, the first and last point of a delayed crossing have the same entry/exit status. Furthermore, the crossing/bouncing flag of delayed crossings and bouncings may be updated. This depends on function specific rules that determine which of the start or end points (if any) should be marked as crossing for used during polygon tracing. A consistent rule is that the start and end points of a delayed crossing will have different crossing/bouncing flags, while a the endpoints of a delayed bounce will be the same.
Used for clipping polygons by other polygons.
julia
function _flag_ent_exit!(::Type{T}, ::GI.LinearRingTrait, poly, pt_list, delay_cross_f, delay_bounce_f; exact) where T
+ npts = length(pt_list)
start_chain_idx = 0
+ for ii in Iterators.flatten((next_idx:npts, 1:start_idx))
+ curr_pt = pt_list[ii]
+ if curr_pt.endpoint == start_chain
+ start_chain_idx = ii
+ elseif curr_pt.crossing || curr_pt.endpoint == end_chain
+ start_crossing, end_crossing = curr_pt.crossing, curr_pt.crossing
+ if curr_pt.endpoint == end_chain # ending overlapping chain
+ start_pt = pt_list[start_chain_idx]
+ if curr_pt.crossing # delayed crossing
+ #= start and end crossing status are different and depend on current
+ entry/exit status =#
+ start_crossing, end_crossing = delay_cross_f(status)
+ else # delayed bouncing
+ next_idx = ii < npts ? (ii + 1) : 1
+ next_val = (curr_pt.point .+ pt_list[next_idx].point) ./ 2
+ pt_in_poly = _point_filled_curve_orientation(next_val, poly; in = true, on = false, out = false, exact)
+ #= start and end crossing status are the same and depend on if adjacent
+ edges of pt_list are within poly =#
+ start_crossing = delay_bounce_f(pt_in_poly)
+ end_crossing = start_crossing
+ end
update start of chain point
julia
pt_list[start_chain_idx] = PolyNode(start_pt; ent_exit = status, crossing = start_crossing)
+ if !curr_pt.crossing
+ status = !status
+ end
+ end
+ pt_list[ii] = PolyNode(curr_pt; ent_exit = status, crossing = end_crossing)
+ status = !status
+ end
+ end
+ return
+end
This function flags all the intersection points as either an 'entry' or 'exit' point in relation to the given line. Returns true if there are crossing points to classify, else returns false. Used for cutting polygons by lines.
Assumes that the first point is outside of the polygon and not on an edge.
julia
function _flag_ent_exit!(::GI.LineTrait, poly, pt_list; exact)
+ status = !_point_filled_curve_orientation(pt_list[1].point, poly; in = true, on = false, out = false, exact)
Loop over points and mark entry and exit status
julia
for (ii, curr_pt) in enumerate(pt_list)
+ if curr_pt.crossing
+ pt_list[ii] = PolyNode(curr_pt; ent_exit = status)
+ status = !status
+ end
+ end
+ return
+end
+
+#= Filters a_idx_list to just include crossing points and sets the index of all crossing
+points (which element they correspond to within a_idx_list). =#
+function _index_crossing_intrs!(a_list, b_list, a_idx_list)
+ filter!(x -> a_list[x].crossing, a_idx_list)
+ for (i, a_idx) in enumerate(a_idx_list)
+ curr_node = a_list[a_idx]
+ neighbor_node = b_list[curr_node.neighbor]
+ a_list[a_idx] = PolyNode(curr_node; idx = i)
+ b_list[curr_node.neighbor] = PolyNode(neighbor_node; idx = i)
+ end
+ return
+end
This function takes the outputs of _build_ab_list and traces the lists to determine which polygons are formed as described in Greiner and Hormann. The function f_step determines in which direction the lists are traced. This function is different for intersection, difference, and union. f_step must take in two arguments: the most recent intersection node's entry/exit status and a boolean that is true if we are currently tracing a_list and false if we are tracing b_list. The functions used for each clipping operation are follows: - Intersection: (x, y) -> x ? 1 : (-1) - Difference: (x, y) -> (x ⊻ y) ? 1 : (-1) - Union: (x, y) -> x ? (-1) : 1
A list of GeoInterface polygons is returned from this function.
Note: poly_a and poly_b are temporary inputs used for debugging and can be removed eventually.
same_status, prev_status = true, curr.ent_exit
+ while same_status
+ @assert visited_pts < total_pts "Clipping tracing hit every point - clipping error. Please open an issue with polygons: $(GI.coordinates(poly_a)) and $(GI.coordinates(poly_b))."
For polygns with no crossing intersection points, either one polygon is inside of another, or they are seperate polygons with no intersection (other than an edge or point).
Return two booleans that represent if a is inside b (potentially with shared edges / points) and visa versa if b is inside of a.
julia
function _find_non_cross_orientation(a_list, b_list, a_poly, b_poly; exact)
+ non_intr_a_idx = findfirst(x -> !x.inter, a_list)
+ non_intr_b_idx = findfirst(x -> !x.inter, b_list)
+ #= Determine if non-intersection point is in or outside of polygon - if there isn't A
+ non-intersection point, then all points are on the polygon edge =#
+ a_pt_orient = isnothing(non_intr_a_idx) ? point_on :
+ _point_filled_curve_orientation(a_list[non_intr_a_idx].point, b_poly; exact)
+ b_pt_orient = isnothing(non_intr_b_idx) ? point_on :
+ _point_filled_curve_orientation(b_list[non_intr_b_idx].point, a_poly; exact)
+ a_in_b = a_pt_orient != point_out && b_pt_orient != point_in
+ b_in_a = b_pt_orient != point_out && a_pt_orient != point_in
+ return a_in_b, b_in_a
+end
The holes specified by the hole iterator are added to the polygons in the return_polys list. If this creates more polygons, they are added to the end of the list. If this removes polygons, they are removed from the list
julia
function _add_holes_to_polys!(::Type{T}, return_polys, hole_iterator, remove_poly_idx; exact) where T
+ n_polys = length(return_polys)
+ remove_hole_idx = Int[]
Remove set of holes from all polygons
julia
for i in 1:n_polys
+ n_new_per_poly = 0
+ for curr_hole in Iterators.map(tuples, hole_iterator) # loop through all holes
loop through all pieces of original polygon (new pieces added to end of list)
julia
for j in Iterators.flatten((i:i, (n_polys + 1):(n_polys + n_new_per_poly)))
+ curr_poly = return_polys[j]
+ remove_poly_idx[j] && continue
+ curr_poly_ext = GI.nhole(curr_poly) > 0 ? GI.Polygon(StaticArrays.SVector(GI.getexterior(curr_poly))) : curr_poly
+ in_ext, on_ext, out_ext = _line_polygon_interactions(curr_hole, curr_poly_ext; exact, closed_line = true)
+ if in_ext # hole is at least partially within the polygon's exterior
+ new_hole, new_hole_poly, n_new_pieces = _combine_holes!(T, curr_hole, curr_poly, return_polys, remove_hole_idx)
+ if n_new_pieces > 0
+ append!(remove_poly_idx, falses(n_new_pieces))
+ n_new_per_poly += n_new_pieces
+ end
+ if !on_ext && !out_ext # hole is completly within exterior
+ push!(curr_poly.geom, new_hole)
+ else # hole is partially within and outside of polygon's exterior
+ new_polys = difference(curr_poly_ext, new_hole_poly, T; target=GI.PolygonTrait())
+ n_new_polys = length(new_polys) - 1
replace original
julia
curr_poly.geom[1] = GI.getexterior(new_polys[1])
+ append!(curr_poly.geom, GI.gethole(new_polys[1]))
+ if n_new_polys > 0 # add any extra pieces
+ append!(return_polys, @view new_polys[2:end])
+ append!(remove_poly_idx, falses(n_new_polys))
+ n_new_per_poly += n_new_polys
+ end
+ end
polygon is completly within hole
julia
elseif coveredby(curr_poly_ext, GI.Polygon(StaticArrays.SVector(curr_hole)))
+ remove_poly_idx[j] = true
+ end
+ end
+ end
+ n_polys += n_new_per_poly
+ end
The new hole is combined with any existing holes in curr_poly. The holes can be combined into a larger hole if they are intersecting. If this happens, then the new, combined hole is returned with the orignal holes making up the new hole removed from curr_poly. Additionally, if the combined holes form a ring, the interior is added to the return_polys as a new polygon piece. Additionally, holes leftover after combination will be checked for it they are in the "main" polygon or in one of these new pieces and moved accordingly.
If the holes don't touch or curr_poly has no holes, then new_hole is returned without any changes.
julia
function _combine_holes!(::Type{T}, new_hole, curr_poly, return_polys, remove_hole_idx) where T
+ n_new_polys = 0
+ empty!(remove_hole_idx)
+ new_hole_poly = GI.Polygon(StaticArrays.SVector(new_hole))
Combine any existing holes in curr_poly with new hole
julia
for (k, old_hole) in enumerate(GI.gethole(curr_poly))
+ old_hole_poly = GI.Polygon(StaticArrays.SVector(old_hole))
+ if intersects(new_hole_poly, old_hole_poly)
If the holes intersect, combine them into a bigger hole
julia
hole_union = union(new_hole_poly, old_hole_poly, T; target = GI.PolygonTrait())[1]
+ push!(remove_hole_idx, k + 1)
+ new_hole = GI.getexterior(hole_union)
+ new_hole_poly = GI.Polygon(StaticArrays.SVector(new_hole))
+ n_pieces = GI.nhole(hole_union)
+ if n_pieces > 0 # if the hole has a hole, then this is a new polygon piece!
+ append!(return_polys, [GI.Polygon([h]) for h in GI.gethole(hole_union)])
+ n_new_polys += n_pieces
+ end
+ end
+ end
If new polygon pieces created, make sure remaining holes are in the correct piece
julia
@views for piece in return_polys[end - n_new_polys + 1:end]
+ for (k, old_hole) in enumerate(GI.gethole(curr_poly))
+ if !(k in remove_hole_idx) && within(old_hole, piece)
+ push!(remove_hole_idx, k + 1)
+ push!(piece.geom, old_hole)
+ end
+ end
+ end
+ deleteat!(curr_poly.geom, remove_hole_idx)
+ return new_hole, new_hole_poly, n_new_polys
+end
+
+#= Remove collinear edge points, other than the first and last edge vertex, to simplify
+polygon - including both the exterior ring and any holes=#
+function _remove_collinear_points!(polys, remove_idx, poly_a, poly_b)
+ for (i, poly) in Iterators.reverse(enumerate(polys))
+ for (j, ring) in Iterators.reverse(enumerate(GI.getring(poly)))
+ n = length(ring.geom)
resize and reset removing index buffer
julia
resize!(remove_idx, n)
+ fill!(remove_idx, false)
+ local p1, p2
+ for (i, p) in enumerate(ring.geom)
+ if i == 1
+ p1 = p
+ continue
+ elseif i == 2
+ p2 = p
+ continue
+ else
+ p3 = p
check if p2 is approximatly on the edge formed by p1 and p3 - remove if so
julia
if Predicates.orient(p1, p2, p3; exact = _False()) == 0
+ remove_idx[i - 1] = true
+ end
+ end
+ p1, p2 = p2, p3
+ end
Check if the first point (which is repeated as the last point) is needed
julia
if Predicates.orient(ring.geom[end - 1], ring.geom[1], ring.geom[2]; exact = _False()) == 0
+ remove_idx[1], remove_idx[end] = true, true
+ end
Remove unneeded collinear points
julia
deleteat!(ring.geom, remove_idx)
Check if enough points are left to form a polygon
julia
if length(ring.geom) ≤ (remove_idx[1] ? 2 : 3)
+ if j == 1
+ deleteat!(polys, i)
+ break
+ else
+ deleteat!(poly.geom, j)
+ continue
+ end
+ end
+ if remove_idx[1] # make sure the last point is repeated
+ push!(ring.geom, ring.geom[1])
+ end
+ end
+ end
+ return
+end
`,169),p=[t];function l(k,e,E,r,d,g){return a(),i("div",null,p)}const c=s(h,[["render",l]]);export{o as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_clipping_clipping_processor.md.CZ0elAO_.lean.js b/previews/PR149/assets/source_methods_clipping_clipping_processor.md.CZ0elAO_.lean.js
new file mode 100644
index 000000000..5f12e8b0a
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_clipping_processor.md.CZ0elAO_.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Polygon clipping helpers","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/clipping_processor.md","filePath":"source/methods/clipping/clipping_processor.md","lastUpdated":null}'),h={name:"source/methods/clipping/clipping_processor.md"},t=n("",169),p=[t];function l(k,e,E,r,d,g){return a(),i("div",null,p)}const c=s(h,[["render",l]]);export{o as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_clipping_coverage.md.CqiKSB6u.js b/previews/PR149/assets/source_methods_clipping_coverage.md.CqiKSB6u.js
new file mode 100644
index 000000000..416d77e6c
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_coverage.md.CqiKSB6u.js
@@ -0,0 +1,223 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/pvgzvkj.Cb0_DiYE.png",c=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/coverage.md","filePath":"source/methods/clipping/coverage.md","lastUpdated":null}'),l={name:"source/methods/clipping/coverage.md"},k=n(`
Coverage is the amount of geometry area within a bounding box defined by the minimum and maximum x and y-coordiantes of that bounding box, or an Extent containing that information.
To provide an example, consider this rectangle:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+rect = GI.Polygon([[(-1,0), (-1,1), (1,1), (1,0), (-1,0)]])
+cell = GI.Polygon([[(0, 0), (0, 2), (2, 2), (2, 0), (0, 0)]])
+xmin, xmax, ymin, ymax = 0, 2, 0, 2
+f, a, p = poly(collect(GI.getpoint(cell)); axis = (; aspect = DataAspect()))
+poly!(collect(GI.getpoint(rect)))
+f
It is clear that half of the polygon is within the cell, so the coverage should be 1.0, half of the area of the rectangle.
This is the GeoInterface-compatible implementation. First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Note that the coverage is zero for all points and curves, even if the curves are closed like with a linear ring.
const UNKNOWN, NORTH, EAST, SOUTH, WEST = 0:4
+
+"""
+ coverage(geom, xmin, xmax, ymin, ymax, [T = Float64])::T
+
+Returns the area of intersection between given geometry and grid cell defined by its minimum
+and maximum x and y-values. This is computed differently for different geometries:
+
+- The signed area of a point is always zero.
+- The signed area of a curve is always zero.
+- The signed area of a polygon is calculated by tracing along its edges and switching to the
+ cell edges if needed.
+- The coverage of a geometry collection, multi-geometry, feature collection of
+ array/iterable is the sum of the coverages of all of the sub-geometries.
+
+Result will be of type T, where T is an optional argument with a default value
+of Float64.
+"""
+function coverage(geom, xmin, xmax, ymin, ymax,::Type{T} = Float64; threaded=false) where T <: AbstractFloat
+ applyreduce(+, _COVERAGE_TARGETS, geom; threaded, init=zero(T)) do g
+ _coverage(T, GI.trait(g), g, T(xmin), T(xmax), T(ymin), T(ymax))
+ end
+end
+
+function coverage(geom, cell_ext::Extents.Extent, ::Type{T} = Float64; threaded=false) where T <: AbstractFloat
+ (xmin, xmax), (ymin, ymax) = values(cell_ext)
+ return coverage(geom, xmin, xmax, ymin, ymax, T; threaded = threaded)
+end
Points, MultiPoints, Curves, MultiCurves
julia
_coverage(::Type{T}, ::GI.AbstractGeometryTrait, geom, xmin, xmax, ymin, ymax; kwargs...) where T = zero(T)
for hole in GI.gethole(poly)
+ cov_area -= _coverage(T, hole, xmin, xmax, ymin, ymax; exact)
+ end
+ return cov_area
+end
+
+#= Calculates the area of the filled ring within the cell defined by corners with (xmin, ymin),
+(xmin, ymax), (xmax, ymax), and (xmax, ymin). =#
+function _coverage(::Type{T}, ring, xmin, xmax, ymin, ymax; exact) where T
+ cov_area = zero(T)
+ unmatched_out_wall, unmatched_out_point = UNKNOWN, (zero(T), zero(T))
+ unmatched_in_wall, unmatched_in_point = unmatched_out_wall, unmatched_out_point
Loop over edges of polygon
julia
start_idx = 1
+ for (i, p) in enumerate(GI.getpoint(ring))
+ if !_point_in_cell(p, xmin, xmax, ymin, ymax)
+ start_idx = i
+ break
+ end
+ end
+ ring_cw = isclockwise(ring)
+ p1 = _tuple_point(GI.getpoint(ring, start_idx), T)
Must rotate clockwise for the algorithm to work
julia
point_idx = ring_cw ? Iterators.flatten((start_idx + 1:GI.npoint(ring), 1:start_idx)) :
+ Iterators.flatten((start_idx - 1:-1:1, GI.npoint(ring):-1:start_idx))
+ for i in point_idx
+ p2 = _tuple_point(GI.getpoint(ring, i), T)
Returns true if b is between a and c, exclusive of the maximum value, else false.
julia
_between(b, a, c) = a ≤ b < c || c ≤ b < a
+
+#= Determine intersections of the line from (x1, y1) to (x2, y2) with the bounding box
+defined by the minimum and maximum x/y values. Since we are dealing with a single line
+segment, we know that there is at maximum two intersection points.
+
+For each intersection point that we find, return the wall that it passes through, as well as
+the intersection point itself as a a tuple. If an intersection point isn't found, return the
+wall as UNKNOWN and the point as a pair of zeros. =#
+function _line_intersect_cell(::Type{T}, (x1, y1), (x2, y2), xmin, xmax, ymin, ymax) where T
+ Δx, Δy = x2 - x1, y2 - y1
+ inter1 = (UNKNOWN, (zero(T), zero(T)))
+ inter2 = inter1
+ if Δx == 0 # If line is vertical, only consider north and south
+ if xmin ≤ x1 ≤ xmax
+ inter1 = _between(ymax, y1, y2) ? (NORTH, (x1, ymax)) : inter1
+ inter2 = _between(ymin, y1, y2) ? (SOUTH, (x1, ymin)) : inter2
+ end
+ elseif Δy == 0 # If line is horizontal, only consider east and west
+ if ymin ≤ y1 ≤ ymax
+ inter1 = _between(xmax, x1, x2) ? (EAST, (xmax, y1)) : inter1
+ inter2 = _between(xmin, x1, x2) ? (WEST, (xmin, y1)) : inter2
+ end
+ else # Line is tilted, must consider all edges, but only two can intersect
+ m = Δy / Δx
+ b = y1 - m * x1
Calculate and check potential intersections
julia
xn = (ymax - b) / m
+ if xmin ≤ xn ≤ xmax && _between(xn, x1, x2) && _between(ymax, y1, y2)
+ inter1 = (NORTH, (xn, ymax))
+ end
+ xs = (ymin - b) / m
+ if xmin ≤ xs ≤ xmax && _between(xs, x1, x2) && _between(ymin, y1, y2)
+ new_intr = (SOUTH, (xs, ymin))
+ (inter1[1] == UNKNOWN) ? (inter1 = new_intr) : (inter2 = new_intr)
+ end
+ ye = m * xmax + b
+ if ymin ≤ ye ≤ ymax && _between(ye, y1, y2) && _between(xmax, x1, x2)
+ new_intr = (EAST, (xmax, ye))
+ (inter1[1] == UNKNOWN) ? (inter1 = new_intr) : (inter2 = new_intr)
+ end
+ yw = m * xmin + b
+ if ymin ≤ yw ≤ ymax && _between(yw, y1, y2) && _between(xmin, x1, x2)
+ new_intr = (WEST, (xmin, yw))
+ (inter1[1] == UNKNOWN) ? (inter1 = new_intr) : (inter2 = new_intr)
+ end
+ end
+ if inter1[1] == UNKNOWN # first intersection must be known, if one exists
+ inter1, inter2 = inter2, inter1
+ end
+ return inter1, inter2
+end
Finds point of cell edge between p1 and p2 given which walls they are on
julia
function find_point_on_cell(p1, p2, wall1, wall2, xmin, xmax, ymin, ymax)
+ x1, y1 = p1
+ x2, y2 = p2
+ mid_point = if wall1 == wall2 && _is_clockwise_from(p1, p2, wall1)
+ (x1 + x2) / 2, (y1 + y2) / 2
+ elseif wall1 == NORTH
+ (xmax, ymax)
+ elseif wall1 == EAST
+ (xmax, ymin)
+ elseif wall1 == SOUTH
+ (xmin, ymin)
+ else
+ (xmin, ymax)
+ end
+ return mid_point
+end
+
+#= Area component of shoelace formula coming from the distance between point 1 and point 2
+along grid cell walls in between the two points. =#
+function connect_edges(::Type{T}, p1, p2, wall1, wall2, xmin, xmax, ymin, ymax) where {T}
+ connect_area = zero(T)
+ if wall1 == wall2 && _is_clockwise_from(p1, p2, wall1)
+ connect_area += _area_component(p1, p2)
+ else
True if (x1, y1) is clockwise from (x2, y2) on the same wall
julia
_is_clockwise_from((x1, y1), (x2, y2), wall) = (wall == NORTH && x2 > x1) ||
+ (wall == EAST && y2 < y1) || (wall == SOUTH && x2 < x1) || (wall == WEST && y2 > y1)
+
+#= Returns the area component of a full edge of the bounding box defined by the min and max
+values and the wall. =#
+_full_edge_area(xmin, xmax, ymin, ymax, wall) = if wall == NORTH
+ ymax * (xmin - xmax)
+ elseif wall == EAST
+ xmax * (ymin - ymax)
+ elseif wall == SOUTH
+ ymin * (xmax - xmin)
+ else
+ xmin * (ymax - ymin)
+ end
+
+#= Returns the area component of part of one wall, from its "starting corner" (going
+clockwise) to the point (x2, y2). =#
+function _partial_edge_in_area((x2, y2), xmin, xmax, ymin, ymax, wall)
+ x_wall = (wall == NORTH || wall == WEST) ? xmin : xmax
+ y_wall = (wall == NORTH || wall == EAST) ? ymax : ymin
+ return x_wall * y2 - x2 * y_wall
+end
+
+#= Returns the area component of part of one wall, from the point (x1, y1) to its
+"ending corner" (going clockwise). =#
+function _partial_edge_out_area((x1, y1), xmin, xmax, ymin, ymax, wall)
+ x_wall = (wall == NORTH || wall == EAST) ? xmax : xmin
+ y_wall = (wall == NORTH || wall == WEST) ? ymax : ymin
+ return x1 * y_wall - x_wall * y1
+end
`,58),p=[k];function t(e,E,r,d,g,y){return a(),i("div",null,p)}const o=s(l,[["render",t]]);export{c as __pageData,o as default};
diff --git a/previews/PR149/assets/source_methods_clipping_coverage.md.CqiKSB6u.lean.js b/previews/PR149/assets/source_methods_clipping_coverage.md.CqiKSB6u.lean.js
new file mode 100644
index 000000000..094c0ce7d
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_coverage.md.CqiKSB6u.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/pvgzvkj.Cb0_DiYE.png",c=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/coverage.md","filePath":"source/methods/clipping/coverage.md","lastUpdated":null}'),l={name:"source/methods/clipping/coverage.md"},k=n("",58),p=[k];function t(e,E,r,d,g,y){return a(),i("div",null,p)}const o=s(l,[["render",t]]);export{c as __pageData,o as default};
diff --git a/previews/PR149/assets/source_methods_clipping_cut.md.D1zx6ccY.js b/previews/PR149/assets/source_methods_clipping_cut.md.D1zx6ccY.js
new file mode 100644
index 000000000..df87b53a5
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_cut.md.D1zx6ccY.js
@@ -0,0 +1,87 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/znyubcg.-VpeHhXX.png",c=JSON.parse('{"title":"Polygon cutting","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/cut.md","filePath":"source/methods/clipping/cut.md","lastUpdated":null}'),t={name:"source/methods/clipping/cut.md"},l=n(`
This function depends on polygon clipping helper function and is inspired by the Greiner-Hormann clipping algorithm used elsewhere in this library. The inspiration came from this Stack Overflow discussion.
julia
"""
+ cut(geom, line, [T::Type])
+
+Return given geom cut by given line as a list of geometries of the same type as the input
+geom. Return the original geometry as only list element if none are found. Line must cut
+fully through given geometry or the original geometry will be returned.
+
+Note: This currently doesn't work for degenerate cases there line crosses through vertices.
+
+# Example
+
+\`\`\`jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+poly = GI.Polygon([[(0.0, 0.0), (10.0, 0.0), (10.0, 10.0), (0.0, 10.0), (0.0, 0.0)]])
+line = GI.Line([(5.0, -5.0), (5.0, 15.0)])
+cut_polys = GO.cut(poly, line)
+GI.coordinates.(cut_polys)
output
julia
2-element Vector{Vector{Vector{Vector{Float64}}}}:
+ [[[0.0, 0.0], [5.0, 0.0], [5.0, 10.0], [0.0, 10.0], [0.0, 0.0]]]
+ [[[5.0, 0.0], [10.0, 0.0], [10.0, 10.0], [5.0, 10.0], [5.0, 0.0]]]
+\`\`\`
+"""
+cut(geom, line, ::Type{T} = Float64) where {T <: AbstractFloat} =
+ _cut(T, GI.trait(geom), geom, GI.trait(line), line; exact = _True())
+
+#= Cut a given polygon by given line. Add polygon holes back into resulting pieces if there
+are any holes. =#
+function _cut(::Type{T}, ::GI.PolygonTrait, poly, ::GI.LineTrait, line; exact) where T
+ ext_poly = GI.getexterior(poly)
+ poly_list, intr_list = _build_a_list(T, ext_poly, line; exact)
+ n_intr_pts = length(intr_list)
If an impossible number of intersection points, return original polygon
julia
if n_intr_pts < 2 || isodd(n_intr_pts)
+ return [tuples(poly)]
+ end
function _cut(::Type{T}, trait::GI.AbstractTrait, geom, line; kwargs...) where T
+ @assert(
+ false,
+ "Cutting of $trait isn't implemented yet.",
+ )
+ return nothing
+end
+
+#= Cutting algorithm inspired by Greiner and Hormann clipping algorithm. Returns coordinates
+of cut geometry in Vector{Vector{Tuple}} format.
+
+Note: degenerate cases where intersection points are vertices do not work right now. =#
+function _cut(::Type{T}, geom, line, geom_list, intr_list, n_intr_pts; exact) where T
Sort and catagorize the intersection points
julia
sort!(intr_list, by = x -> geom_list[x].fracs[2])
+ _flag_ent_exit!(GI.LineTrait(), line, geom_list; exact)
`,34),p=[l];function k(e,r,E,d,g,y){return a(),i("div",null,p)}const F=s(t,[["render",k]]);export{c as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_clipping_cut.md.D1zx6ccY.lean.js b/previews/PR149/assets/source_methods_clipping_cut.md.D1zx6ccY.lean.js
new file mode 100644
index 000000000..c0cf81908
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_cut.md.D1zx6ccY.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/znyubcg.-VpeHhXX.png",c=JSON.parse('{"title":"Polygon cutting","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/cut.md","filePath":"source/methods/clipping/cut.md","lastUpdated":null}'),t={name:"source/methods/clipping/cut.md"},l=n("",34),p=[l];function k(e,r,E,d,g,y){return a(),i("div",null,p)}const F=s(t,[["render",k]]);export{c as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_clipping_difference.md.Bm3W4a7c.js b/previews/PR149/assets/source_methods_clipping_difference.md.Bm3W4a7c.js
new file mode 100644
index 000000000..4d055404d
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_difference.md.Bm3W4a7c.js
@@ -0,0 +1,156 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Difference Polygon Clipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/difference.md","filePath":"source/methods/clipping/difference.md","lastUpdated":null}'),l={name:"source/methods/clipping/difference.md"},p=n(`
export difference
+
+
+"""
+ difference(geom_a, geom_b, [T::Type]; target::Type, fix_multipoly = UnionIntersectingPolygons())
+
+Return the difference between two geometries as a list of geometries. Return an empty list
+if none are found. The type of the list will be constrained as much as possible given the
+input geometries. Furthermore, the user can provide a \`taget\` type as a keyword argument and
+a list of target geometries found in the difference will be returned. The user can also
+provide a float type that they would like the points of returned geometries to be. If the
+user is taking a intersection involving one or more multipolygons, and the multipolygon
+might be comprised of polygons that intersect, if \`fix_multipoly\` is set to an
+\`IntersectingPolygons\` correction (the default is \`UnionIntersectingPolygons()\`), then the
+needed multipolygons will be fixed to be valid before performing the intersection to ensure
+a correct answer. Only set \`fix_multipoly\` to false if you know that the multipolygons are
+valid, as it will avoid unneeded computation.
+
+# Example
+
+\`\`\`jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+poly1 = GI.Polygon([[[0.0, 0.0], [5.0, 5.0], [10.0, 0.0], [5.0, -5.0], [0.0, 0.0]]])
+poly2 = GI.Polygon([[[3.0, 0.0], [8.0, 5.0], [13.0, 0.0], [8.0, -5.0], [3.0, 0.0]]])
+diff_poly = GO.difference(poly1, poly2; target = GI.PolygonTrait())
+GI.coordinates.(diff_poly)
output
julia
1-element Vector{Vector{Vector{Vector{Float64}}}}:
+ [[[6.5, 3.5], [5.0, 5.0], [0.0, 0.0], [5.0, -5.0], [6.5, -3.5], [3.0, 0.0], [6.5, 3.5]]]
+\`\`\`
+"""
+function difference(
+ geom_a, geom_b, ::Type{T} = Float64; target=nothing, kwargs...,
+) where {T<:AbstractFloat}
+ return _difference(
+ TraitTarget(target), T, GI.trait(geom_a), geom_a, GI.trait(geom_b), geom_b;
+ exact = _True(), kwargs...,
+ )
+end
+
+#= The 'difference' function returns the difference of two polygons as a list of polygons.
+The algorithm to determine the difference was adapted from "Efficient clipping of efficient
+polygons," by Greiner and Hormann (1998). DOI: https://doi.org/10.1145/274363.274364 =#
+function _difference(
+ ::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.PolygonTrait, poly_a,
+ ::GI.PolygonTrait, poly_b;
+ exact, kwargs...
+) where T
add case for if they polygons are the same (all intersection points!) add a find_first check to find first non-inter poly!
julia
if b_in_a && !a_in_b # b in a and can't be the same polygon
+ poly_a_b_hole = GI.Polygon([tuples(ext_a), tuples(ext_b)])
+ push!(polys, poly_a_b_hole)
+ elseif !b_in_a && !a_in_b # polygons don't intersect
+ push!(polys, tuples(poly_a))
+ return polys
+ end
+ end
+ remove_idx = falses(length(polys))
If the original polygons had holes, take that into account.
julia
if GI.nhole(poly_a) != 0
+ _add_holes_to_polys!(T, polys, GI.gethole(poly_a), remove_idx; exact)
+ end
+ if GI.nhole(poly_b) != 0
+ for hole in GI.gethole(poly_b)
+ hole_poly = GI.Polygon(StaticArrays.SVector(hole))
+ new_polys = intersection(hole_poly, poly_a, T; target = GI.PolygonTrait)
+ if length(new_polys) > 0
+ append!(polys, new_polys)
+ end
+ end
+ end
Helper functions for Differences with Greiner and Hormann Polygon Clipping
julia
#= When marking the crossing status of a delayed crossing, the chain start point is crossing
+when the start point is a entry point and is a bouncing point when the start point is an
+exit point. The end of the chain has the opposite crossing / bouncing status. =#
+_diff_delay_cross_f(x) = (x, !x)
+#= When marking the crossing status of a delayed bouncing, the chain start and end points
+are crossing if the current polygon's adjacent edges are within the non-tracing polygon and
+we are tracing b_list or if the edges are outside and we are on a_list. Otherwise the
+endpoints are marked as crossing. x is a boolean representing if the edges are inside or
+outside of the polygon and y is a variable that is true if we are on a_list and false if we
+are on b_list. =#
+_diff_delay_bounce_f(x, y) = x ⊻ y
+#= When tracing polygons, step forwards if the most recent intersection point was an entry
+point and we are currently tracing b_list or if it was an exit point and we are currently
+tracing a_list, else step backwards, where x is the entry/exit status and y is a variable
+that is true if we are on a_list and false if we are on b_list. =#
+_diff_step(x, y) = (x ⊻ y) ? 1 : (-1)
+
+#= Polygon with multipolygon difference - note that all intersection regions between
+\`poly_a\` and any of the sub-polygons of \`multipoly_b\` are removed from \`poly_a\`. =#
+function _difference(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.PolygonTrait, poly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ kwargs...,
+) where T
+ polys = [tuples(poly_a, T)]
+ for poly_b in GI.getpolygon(multipoly_b)
+ isempty(polys) && break
+ polys = mapreduce(p -> difference(p, poly_b; target), append!, polys)
+ end
+ return polys
+end
+
+#= Multipolygon with polygon difference - note that all intersection regions between
+sub-polygons of \`multipoly_a\` and \`poly_b\` will be removed from the corresponding
+sub-polygon. Unless specified with \`fix_multipoly = nothing\`, \`multipolygon_a\` will be
+validated using the given (default is \`UnionIntersectingPolygons()\`) correction. =#
+function _difference(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.PolygonTrait, poly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix multipoly_a to prevent returning an invalid multipolygon
+ multipoly_a = fix_multipoly(multipoly_a)
+ end
+ polys = Vector{_get_poly_type(T)}()
+ sizehint!(polys, GI.npolygon(multipoly_a))
+ for poly_a in GI.getpolygon(multipoly_a)
+ append!(polys, difference(poly_a, poly_b; target))
+ end
+ return polys
+end
+
+#= Multipolygon with multipolygon difference - note that all intersection regions between
+sub-polygons of \`multipoly_a\` and sub-polygons of \`multipoly_b\` will be removed from the
+corresponding sub-polygon of \`multipoly_a\`. Unless specified with \`fix_multipoly = nothing\`,
+\`multipolygon_a\` will be validated using the given (defauly is \`UnionIntersectingPolygons()\`)
+correction. =#
+function _difference(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix multipoly_a to prevent returning an invalid multipolygon
+ multipoly_a = fix_multipoly(multipoly_a)
+ fix_multipoly = nothing
+ end
+ local polys
+ for (i, poly_b) in enumerate(GI.getpolygon(multipoly_b))
+ polys = difference(i == 1 ? multipoly_a : GI.MultiPolygon(polys), poly_b; target, fix_multipoly)
+ end
+ return polys
+end
Many type and target combos aren't implemented
julia
function _difference(
+ ::TraitTarget{Target}, ::Type{T},
+ trait_a::GI.AbstractTrait, geom_a,
+ trait_b::GI.AbstractTrait, geom_b,
+) where {Target, T}
+ @assert(
+ false,
+ "Difference between $trait_a and $trait_b with target $Target isn't implemented yet.",
+ )
+ return nothing
+end
`,22),t=[p];function h(e,k,r,d,g,y){return a(),i("div",null,t)}const F=s(l,[["render",h]]);export{o as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_clipping_difference.md.Bm3W4a7c.lean.js b/previews/PR149/assets/source_methods_clipping_difference.md.Bm3W4a7c.lean.js
new file mode 100644
index 000000000..817c8d0fc
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_difference.md.Bm3W4a7c.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Difference Polygon Clipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/difference.md","filePath":"source/methods/clipping/difference.md","lastUpdated":null}'),l={name:"source/methods/clipping/difference.md"},p=n("",22),t=[p];function h(e,k,r,d,g,y){return a(),i("div",null,t)}const F=s(l,[["render",h]]);export{o as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_clipping_intersection.md.C-VLWIZU.js b/previews/PR149/assets/source_methods_clipping_intersection.md.C-VLWIZU.js
new file mode 100644
index 000000000..a34c9f102
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_intersection.md.C-VLWIZU.js
@@ -0,0 +1,388 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Geometry Intersection","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/intersection.md","filePath":"source/methods/clipping/intersection.md","lastUpdated":null}'),t={name:"source/methods/clipping/intersection.md"},h=n(`
export intersection, intersection_points
+
+"""
+ Enum LineOrientation
+Enum for the orientation of a line with respect to a curve. A line can be
+\`line_cross\` (crossing over the curve), \`line_hinge\` (crossing the endpoint of the curve),
+\`line_over\` (colinear with the curve), or \`line_out\` (not interacting with the curve).
+"""
+@enum LineOrientation line_cross=1 line_hinge=2 line_over=3 line_out=4
+
+"""
+ intersection(geom_a, geom_b, [T::Type]; target::Type, fix_multipoly = UnionIntersectingPolygons())
+
+Return the intersection between two geometries as a list of geometries. Return an empty list
+if none are found. The type of the list will be constrained as much as possible given the
+input geometries. Furthermore, the user can provide a \`target\` type as a keyword argument and
+a list of target geometries found in the intersection will be returned. The user can also
+provide a float type that they would like the points of returned geometries to be. If the
+user is taking a intersection involving one or more multipolygons, and the multipolygon
+might be comprised of polygons that intersect, if \`fix_multipoly\` is set to an
+\`IntersectingPolygons\` correction (the default is \`UnionIntersectingPolygons()\`), then the
+needed multipolygons will be fixed to be valid before performing the intersection to ensure
+a correct answer. Only set \`fix_multipoly\` to nothing if you know that the multipolygons are
+valid, as it will avoid unneeded computation.
+
+# Example
+
+\`\`\`jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+line1 = GI.Line([(124.584961,-12.768946), (126.738281,-17.224758)])
+line2 = GI.Line([(123.354492,-15.961329), (127.22168,-14.008696)])
+inter_points = GO.intersection(line1, line2; target = GI.PointTrait())
+GI.coordinates.(inter_points)
Helper functions for Intersections with Greiner and Hormann Polygon Clipping
julia
#= When marking the crossing status of a delayed crossing, the chain start point is bouncing
+when the start point is a entry point and is a crossing point when the start point is an
+exit point. The end of the chain has the opposite crossing / bouncing status. x is the
+entry/exit status. =#
+_inter_delay_cross_f(x) = (!x, x)
+#= When marking the crossing status of a delayed bouncing, the chain start and end points
+are crossing if the current polygon's adjacent edges are within the non-tracing polygon. If
+the edges are outside then the chain endpoints are marked as bouncing. x is a boolean
+representing if the edges are inside or outside of the polygon. =#
+_inter_delay_bounce_f(x, _) = x
+#= When tracing polygons, step forward if the most recent intersection point was an entry
+point, else step backwards where x is the entry/exit status. =#
+_inter_step(x, _) = x ? 1 : (-1)
+
+#= Polygon with multipolygon intersection - note that all intersection regions between
+\`poly_a\` and any of the sub-polygons of \`multipoly_b\` are counted as intersection polygons.
+Unless specified with \`fix_multipoly = nothing\`, \`multipolygon_b\` will be validated using
+the given (default is \`UnionIntersectingPolygons()\`) correction. =#
+function _intersection(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.PolygonTrait, poly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix multipoly_b to prevent duplicated intersection regions
+ multipoly_b = fix_multipoly(multipoly_b)
+ end
+ polys = Vector{_get_poly_type(T)}()
+ for poly_b in GI.getpolygon(multipoly_b)
+ append!(polys, intersection(poly_a, poly_b; target))
+ end
+ return polys
+end
+
+#= Multipolygon with polygon intersection is equivalent to taking the intersection of the
+poylgon with the multipolygon and thus simply switches the order of operations and calls the
+above method. =#
+_intersection(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.PolygonTrait, poly_b;
+ kwargs...,
+) where T = intersection(poly_b, multipoly_a; target , kwargs...)
+
+#= Multipolygon with multipolygon intersection - note that all intersection regions between
+any sub-polygons of \`multipoly_a\` and any of the sub-polygons of \`multipoly_b\` are counted
+as intersection polygons. Unless specified with \`fix_multipoly = nothing\`, both
+\`multipolygon_a\` and \`multipolygon_b\` will be validated using the given (default is
+\`UnionIntersectingPolygons()\`) correction. =#
+function _intersection(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix both multipolygons to prevent duplicated regions
+ multipoly_a = fix_multipoly(multipoly_a)
+ multipoly_b = fix_multipoly(multipoly_b)
+ fix_multipoly = nothing
+ end
+ polys = Vector{_get_poly_type(T)}()
+ for poly_a in GI.getpolygon(multipoly_a)
+ append!(polys, intersection(poly_a, multipoly_b; target, fix_multipoly))
+ end
+ return polys
+end
Many type and target combos aren't implemented
julia
function _intersection(
+ ::TraitTarget{Target}, ::Type{T},
+ trait_a::GI.AbstractTrait, geom_a,
+ trait_b::GI.AbstractTrait, geom_b;
+ kwargs...,
+) where {Target, T}
+ @assert(
+ false,
+ "Intersection between $trait_a and $trait_b with target $Target isn't implemented yet.",
+ )
+ return nothing
+end
+
+"""
+ intersection_points(
+ geom_a,
+ geom_b,
+ )::Union{
+ ::Vector{::Tuple{::Real, ::Real}},
+ ::Nothing,
+ }
+
+Return a list of intersection points between two geometries of type GI.Point.
+If no intersection point was possible given geometry extents, returns an empty
+list.
+"""
+intersection_points(geom_a, geom_b, ::Type{T} = Float64) where T <: AbstractFloat =
+ _intersection_points(T, GI.trait(geom_a), geom_a, GI.trait(geom_b), geom_b)
+
+
+#= Calculates the list of intersection points between two geometries, inlcuding line
+segments, line strings, linear rings, polygons, and multipolygons. If no intersection points
+were possible given geometry extents or if none are found, return an empty list of
+GI.Points. =#
+function _intersection_points(::Type{T}, ::GI.AbstractTrait, a, ::GI.AbstractTrait, b; exact = _False()) where T
Initialize an empty list of points
julia
result = GI.Point[]
Check if the geometries extents even overlap
julia
Extents.intersects(GI.extent(a), GI.extent(b)) || return result
Create a list of edges from the two input geometries
Loop over pairs of edges and add any intersection points to results
julia
for i in eachindex(edges_a), j in eachindex(edges_b)
+ line_orient, intr1, _ = _intersection_point(T, edges_a[i], edges_b[j]; exact)
TODO: Add in degenerate intersection points when line_over
julia
if line_orient == line_cross || line_orient == line_hinge
+ #=
+ Determine if point is on edge (all edge endpoints excluded
+ except for the last edge for an open geometry)
+ =#
+ point, (α, β) = intr1
+ on_a_edge = (!a_closed && i == npoints_a && 0 <= α <= 1) ||
+ (0 <= α < 1)
+ on_b_edge = (!b_closed && j == npoints_b && 0 <= β <= 1) ||
+ (0 <= β < 1)
+ if on_a_edge && on_b_edge
+ push!(result, GI.Point(point))
+ end
+ end
+ end
+ end
+ return result
+end
+
+#= Calculates the intersection points between two lines if they exists and the fractional
+component of each line from the initial end point to the intersection point where α is the
+fraction along (a1, a2) and β is the fraction along (b1, b2).
+
+Note that the first return is the type of intersection (line_cross, line_hinge, line_over,
+or line_out). The type of intersection determines how many intersection points there are.
+If the intersection is line_out, then there are no intersection points and the two
+intersections aren't valid and shouldn't be used. If the intersection is line_cross or
+line_hinge then the lines meet at one point and the first intersection is valid, while the
+second isn't. Finally, if the intersection is line_over, then both points are valid and they
+are the two points that define the endpoints of the overlapping region between the two
+lines.
+
+Also note again that each intersection is a tuple of two tuples. The first is the
+intersection point (x,y) while the second is the ratio along the initial lines (α, β) for
+that point.
+
+Calculation derivation can be found here: https://stackoverflow.com/questions/563198/ =#
+function _intersection_point(::Type{T}, (a1, a2)::Edge, (b1, b2)::Edge; exact) where T
Intersection is a cross if there is only one non-endpoint intersection point
julia
line_orient = line_cross
+ intr1 = _find_cross_intersection(T, a1, a2, b1, b2, a_ext, b_ext)
+ end
+ return line_orient, intr1, intr2
+end
+
+#= If lines defined by (a1, a2) and (b1, b2) are collinear, find endpoints of overlapping
+region if they exist. This could result in three possibilities. First, there could be no
+overlapping region, in which case, the default 'no_intr_result' intersection information is
+returned. Second, the two regions could just meet at one shared endpoint, in which case it
+is a hinge intersection with one intersection point. Otherwise, it is a overlapping
+intersection defined by two of the endpoints of the line segments. =#
+function _find_collinear_intersection(::Type{T}, a1, a2, b1, b2, a_ext, b_ext, no_intr_result) where T
if a1_in_b && a2_in_b # 1st vertex of a and 2nd vertex of a form overlap
+ line_orient = line_over
+ β1 = _clamped_frac(distance(a1, b1, T), b_dist)
+ β2 = _clamped_frac(distance(a2, b1, T), b_dist)
+ intr1 = (_tuple_point(a1, T), (zero(T), β1))
+ intr2 = (_tuple_point(a2, T), (one(T), β2))
+ elseif b1_in_a && b2_in_a # 1st vertex of b and 2nd vertex of b form overlap
+ line_orient = line_over
+ α1 = _clamped_frac(distance(b1, a1, T), a_dist)
+ α2 = _clamped_frac(distance(b2, a1, T), a_dist)
+ intr1 = (_tuple_point(b1, T), (α1, zero(T)))
+ intr2 = (_tuple_point(b2, T), (α2, one(T)))
+ elseif a1_in_b && b1_in_a # 1st vertex of a and 1st vertex of b form overlap
+ if equals(a1, b1)
+ line_orient = line_hinge
+ intr1 = (_tuple_point(a1, T), (zero(T), zero(T)))
+ else
+ line_orient = line_over
+ intr1, intr2 = _set_ab_collinear_intrs(T, a1, b1, zero(T), zero(T), a1, b1, a_dist, b_dist)
+ end
+ elseif a1_in_b && b2_in_a # 1st vertex of a and 2nd vertex of b form overlap
+ if equals(a1, b2)
+ line_orient = line_hinge
+ intr1 = (_tuple_point(a1, T), (zero(T), one(T)))
+ else
+ line_orient = line_over
+ intr1, intr2 = _set_ab_collinear_intrs(T, a1, b2, zero(T), one(T), a1, b1, a_dist, b_dist)
+ end
+ elseif a2_in_b && b1_in_a # 2nd vertex of a and 1st vertex of b form overlap
+ if equals(a2, b1)
+ line_orient = line_hinge
+ intr1 = (_tuple_point(a2, T), (one(T), zero(T)))
+ else
+ line_orient = line_over
+ intr1, intr2 = _set_ab_collinear_intrs(T, a2, b1, one(T), zero(T), a1, b1, a_dist, b_dist)
+ end
+ elseif a2_in_b && b2_in_a # 2nd vertex of a and 2nd vertex of b form overlap
+ if equals(a2, b2)
+ line_orient = line_hinge
+ intr1 = (_tuple_point(a2, T), (one(T), one(T)))
+ else
+ line_orient = line_over
+ intr1, intr2 = _set_ab_collinear_intrs(T, a2, b2, one(T), one(T), a1, b1, a_dist, b_dist)
+ end
+ end
+ return line_orient, intr1, intr2
+end
+
+#= Determine intersection points and segment fractions when overlap is made up one one
+endpoint of segment (a1, a2) and one endpoint of segment (b1, b2). =#
+_set_ab_collinear_intrs(::Type{T}, a_pt, b_pt, a_pt_α, b_pt_β, a1, b1, a_dist, b_dist) where T =
+ (
+ (_tuple_point(a_pt, T), (a_pt_α, _clamped_frac(distance(a_pt, b1, T), b_dist))),
+ (_tuple_point(b_pt, T), (_clamped_frac(distance(b_pt, a1, T), a_dist), b_pt_β))
+ )
+
+#= If lines defined by (a1, a2) and (b1, b2) are just touching at one of those endpoints and
+are not collinear, then they form a hinge, with just that one shared intersection point.
+Point equality is checked before segment orientation to have maximal accurary on fractions
+to avoid floating point errors. If the points are not equal, we know that the hinge does not
+take place at an endpoint and the fractions must be between 0 or 1 (exclusive). =#
+function _find_hinge_intersection(::Type{T}, a1, a2, b1, b2, a1_orient, a2_orient, b1_orient) where T
+ pt, α, β = if equals(a1, b1)
+ _tuple_point(a1, T), zero(T), zero(T)
+ elseif equals(a1, b2)
+ _tuple_point(a1, T), zero(T), one(T)
+ elseif equals(a2, b1)
+ _tuple_point(a2, T), one(T), zero(T)
+ elseif equals(a2, b2)
+ _tuple_point(a2, T), one(T), one(T)
+ elseif a1_orient == 0
+ β_val = _clamped_frac(distance(b1, a1, T), distance(b1, b2, T), eps(T))
+ _tuple_point(a1, T), zero(T), β_val
+ elseif a2_orient == 0
+ β_val = _clamped_frac(distance(b1, a2, T), distance(b1, b2, T), eps(T))
+ _tuple_point(a2, T), one(T), β_val
+ elseif b1_orient == 0
+ α_val = _clamped_frac(distance(a1, b1, T), distance(a1, a2, T), eps(T))
+ _tuple_point(b1, T), α_val, zero(T)
+ else # b2_orient == 0
+ α_val = _clamped_frac(distance(a1, b2, T), distance(a1, a2, T), eps(T))
+ _tuple_point(b2, T), α_val, one(T)
+ end
+ return pt, (α, β)
+end
+
+#= If lines defined by (a1, a2) and (b1, b2) meet at one point that is not an endpoint of
+either segment, they form a crossing intersection with a singular intersection point. That
+point is caculated by finding the fractional distance along each segment the point occurs
+at (α, β). If the point is too close to an endpoint to be distinct, the point shares a value
+with the endpoint, but with a non-zero and non-one fractional value. If the intersection
+point calculated is outside of the envelope of the two segments due to floating point error,
+it is set to the endpoint of the two segments that is closest to the other segment.
+Regardless of point value, we know that it does not actually occur at an endpoint so the
+fractions must be between 0 or 1 (exclusive). =#
+function _find_cross_intersection(::Type{T}, a1, a2, b1, b2, a_ext, b_ext) where T
Determine α value where 0 < α < 1 and β value where 0 < β < 1
julia
α = _clamped_frac(Δbax * Δby - Δbay * Δbx, a_cross_b, eps(T))
+ β = _clamped_frac(Δbax * Δay - Δbay * Δax, a_cross_b, eps(T))
+
+ #= Intersection will be where a1 + α * Δa = b1 + β * Δb. However, due to floating point
+ innacurracies, α and β calculations may yeild different intersection points. Average
+ both points together to minimize difference from real value, as long as segment isn't
+ vertical or horizontal as this will almost certianly lead to the point being outside the
+ envelope due to floating point error. Also note that floating point limitations could
+ make intersection be endpoint if α≈0 or α≈1.=#
+ x = if Δax == 0
+ a1x
+ elseif Δbx == 0
+ b1x
+ else
+ (a1x + α * Δax + b1x + β * Δbx) / 2
+ end
+ y = if Δay == 0
+ a1y
+ elseif Δby == 0
+ b1y
+ else
+ (a1y + α * Δay + b1y + β * Δby) / 2
+ end
+ pt = (x, y)
Check if point is within segment envelopes and adjust to endpoint if not
`,80),l=[h];function p(k,e,E,r,d,g){return a(),i("div",null,l)}const F=s(t,[["render",p]]);export{o as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_clipping_intersection.md.C-VLWIZU.lean.js b/previews/PR149/assets/source_methods_clipping_intersection.md.C-VLWIZU.lean.js
new file mode 100644
index 000000000..959f67b8e
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_intersection.md.C-VLWIZU.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Geometry Intersection","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/intersection.md","filePath":"source/methods/clipping/intersection.md","lastUpdated":null}'),t={name:"source/methods/clipping/intersection.md"},h=n("",80),l=[h];function p(k,e,E,r,d,g){return a(),i("div",null,l)}const F=s(t,[["render",p]]);export{o as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_clipping_predicates.md.BOrMErzK.js b/previews/PR149/assets/source_methods_clipping_predicates.md.BOrMErzK.js
new file mode 100644
index 000000000..c36c2923c
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_predicates.md.BOrMErzK.js
@@ -0,0 +1,44 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"If we want to inject adaptivity, we would do something like:","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/predicates.md","filePath":"source/methods/clipping/predicates.md","lastUpdated":null}'),t={name:"source/methods/clipping/predicates.md"},h=n(`
julia
module Predicates
+ using ExactPredicates, ExactPredicates.Codegen
+ import ExactPredicates: ext
+ import ExactPredicates.Codegen: group!, @genpredicate
+ import GeometryOps: _False, _True, _booltype, _tuple_point
+ import GeoInterface as GI
+
+ #= Determine the orientation of c with regards to the oriented segment (a, b).
+ Return 1 if c is to the left of (a, b).
+ Return -1 if c is to the right of (a, b).
+ Return 0 if c is on (a, b) or if a == b. =#
+ orient(a, b, c; exact) = _orient(_booltype(exact), a, b, c)
If exact is true, use ExactPredicates to calculate the orientation.
julia
_orient(::_True, a, b, c) = ExactPredicates.orient(_tuple_point(a, Float64), _tuple_point(b, Float64), _tuple_point(c, Float64))
If exact is false, calculate the orientation without using ExactPredicates.
julia
function _orient(exact::_False, a, b, c)
+ a = a .- c
+ b = b .- c
+ return _cross(exact, a, b)
+ end
+
+ #= Determine the sign of the cross product of a and b.
+ Return 1 if the cross product is positive.
+ Return -1 if the cross product is negative.
+ Return 0 if the cross product is 0. =#
+ cross(a, b; exact) = _cross(_booltype(exact), a, b)
+
+ #= If \`exact\` is \`true\`, use exact cross product calculation created using
+ \`ExactPredicates\`generated predicate. Note that as of now \`ExactPredicates\` requires
+ Float64 so we must convert points a and b. =#
+ _cross(::_True, a, b) = _cross_exact(_tuple_point(a, Float64), _tuple_point(b, Float64))
Exact cross product calculation using ExactPredicates.
julia
@genpredicate function _cross_exact(a :: 2, b :: 2)
+ group!(a...)
+ group!(b...)
+ ext(a, b)
+ end
If exact is false, calculate the cross product without using ExactPredicates.
julia
function _cross(::_False, a, b)
+ c_t1 = GI.x(a) * GI.y(b)
+ c_t2 = GI.y(a) * GI.x(b)
+ c_val = if isapprox(c_t1, c_t2)
+ 0
+ else
+ sign(c_t1 - c_t2)
+ end
+ return c_val
+ end
+
+end
+
+import .Predicates
If we want to inject adaptivity, we would do something like:
function cross(a, b, c) # try Predicates._cross_naive(a, b, c) # check the error bound there # then try Predicates._cross_adaptive(a, b, c) # then try Predicates._cross_exact end
`,13),e=[h];function p(l,k,r,d,E,c){return a(),i("div",null,e)}const y=s(t,[["render",p]]);export{o as __pageData,y as default};
diff --git a/previews/PR149/assets/source_methods_clipping_predicates.md.BOrMErzK.lean.js b/previews/PR149/assets/source_methods_clipping_predicates.md.BOrMErzK.lean.js
new file mode 100644
index 000000000..7eceaf8bf
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_predicates.md.BOrMErzK.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"If we want to inject adaptivity, we would do something like:","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/predicates.md","filePath":"source/methods/clipping/predicates.md","lastUpdated":null}'),t={name:"source/methods/clipping/predicates.md"},h=n("",13),e=[h];function p(l,k,r,d,E,c){return a(),i("div",null,e)}const y=s(t,[["render",p]]);export{o as __pageData,y as default};
diff --git a/previews/PR149/assets/source_methods_clipping_union.md.CTJa5OQM.js b/previews/PR149/assets/source_methods_clipping_union.md.CTJa5OQM.js
new file mode 100644
index 000000000..0a08cee3f
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_union.md.CTJa5OQM.js
@@ -0,0 +1,250 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Union Polygon Clipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/union.md","filePath":"source/methods/clipping/union.md","lastUpdated":null}'),l={name:"source/methods/clipping/union.md"},h=n(`
export union
+
+"""
+ union(geom_a, geom_b, [::Type{T}]; target::Type, fix_multipoly = UnionIntersectingPolygons())
+
+Return the union between two geometries as a list of geometries. Return an empty list if
+none are found. The type of the list will be constrained as much as possible given the input
+geometries. Furthermore, the user can provide a \`taget\` type as a keyword argument and a
+list of target geometries found in the difference will be returned. The user can also
+provide a float type 'T' that they would like the points of returned geometries to be. If
+the user is taking a intersection involving one or more multipolygons, and the multipolygon
+might be comprised of polygons that intersect, if \`fix_multipoly\` is set to an
+\`IntersectingPolygons\` correction (the default is \`UnionIntersectingPolygons()\`), then the
+needed multipolygons will be fixed to be valid before performing the intersection to ensure
+a correct answer. Only set \`fix_multipoly\` to false if you know that the multipolygons are
+valid, as it will avoid unneeded computation.
+
+Calculates the union between two polygons.
+# Example
+
+\`\`\`jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+p1 = GI.Polygon([[(0.0, 0.0), (5.0, 5.0), (10.0, 0.0), (5.0, -5.0), (0.0, 0.0)]])
+p2 = GI.Polygon([[(3.0, 0.0), (8.0, 5.0), (13.0, 0.0), (8.0, -5.0), (3.0, 0.0)]])
+union_poly = GO.union(p1, p2; target = GI.PolygonTrait())
+GI.coordinates.(union_poly)
output
julia
1-element Vector{Vector{Vector{Vector{Float64}}}}:
+ [[[6.5, 3.5], [5.0, 5.0], [0.0, 0.0], [5.0, -5.0], [6.5, -3.5], [8.0, -5.0], [13.0, 0.0], [8.0, 5.0], [6.5, 3.5]]]
+\`\`\`
+"""
+function union(
+ geom_a, geom_b, ::Type{T}=Float64; target=nothing, kwargs...
+) where {T<:AbstractFloat}
+ return _union(
+ TraitTarget(target), T, GI.trait(geom_a), geom_a, GI.trait(geom_b), geom_b;
+ exact = _True(), kwargs...,
+ )
+end
+
+#= This 'union' implementation returns the union of two polygons. The algorithm to determine
+the union was adapted from "Efficient clipping of efficient polygons," by Greiner and
+Hormann (1998). DOI: https://doi.org/10.1145/274363.274364 =#
+function _union(
+ ::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.PolygonTrait, poly_a,
+ ::GI.PolygonTrait, poly_b;
+ exact, kwargs...,
+) where T
Check if one polygon totally within other and if so, return the larger polygon
julia
a_in_b, b_in_a = false, false
+ if n_pieces == 0 # no crossing points, determine if either poly is inside the other
+ a_in_b, b_in_a = _find_non_cross_orientation(a_list, b_list, ext_a, ext_b; exact)
+ if a_in_b
+ push!(polys, GI.Polygon([tuples(ext_b)]))
+ elseif b_in_a
+ push!(polys, GI.Polygon([tuples(ext_a)]))
+ else
+ push!(polys, tuples(poly_a))
+ push!(polys, tuples(poly_b))
+ return polys
+ end
+ elseif n_pieces > 1
+ #= extra polygons are holes (n_pieces == 1 is the desired state) and since
+ holes are formed by regions exterior to both poly_a and poly_b, they can't interact
+ with pre-existing holes =#
+ sort!(polys, by = area, rev = true) # sort by area so first element is the exterior
the first element is the exterior, the rest are holes
julia
@views append!(polys[1].geom, (GI.getexterior(p) for p in polys[2:end]))
+ keepat!(polys, 1)
+ end
Add in holes
julia
if GI.nhole(poly_a) != 0 || GI.nhole(poly_b) != 0
+ _add_union_holes!(polys, a_in_b, b_in_a, poly_a, poly_b; exact)
+ end
Helper functions for Unions with Greiner and Hormann Polygon Clipping
julia
#= When marking the crossing status of a delayed crossing, the chain start point is crossing
+when the start point is a entry point and is a bouncing point when the start point is an
+exit point. The end of the chain has the opposite crossing / bouncing status. =#
+_union_delay_cross_f(x) = (x, !x)
+
+#= When marking the crossing status of a delayed bouncing, the chain start and end points
+are bouncing if the current polygon's adjacent edges are within the non-tracing polygon. If
+the edges are outside then the chain endpoints are marked as crossing. x is a boolean
+representing if the edges are inside or outside of the polygon. =#
+_union_delay_bounce_f(x, _) = !x
+
+#= When tracing polygons, step backwards if the most recent intersection point was an entry
+point, else step forwards where x is the entry/exit status. =#
+_union_step(x, _) = x ? (-1) : 1
+
+#= Add holes from two polygons to the exterior polygon formed by their union. If adding the
+the holes reveals that the polygons aren't actually intersecting, return the original
+polygons. =#
+function _add_union_holes!(polys, a_in_b, b_in_a, poly_a, poly_b; exact)
+ if a_in_b
+ _add_union_holes_contained_polys!(polys, poly_a, poly_b; exact)
+ elseif b_in_a
+ _add_union_holes_contained_polys!(polys, poly_b, poly_a; exact)
+ else # Polygons intersect, but neither is contained in the other
+ n_a_holes = GI.nhole(poly_a)
+ ext_poly_a = GI.Polygon(StaticArrays.SVector(GI.getexterior(poly_a)))
+ ext_poly_b = GI.Polygon(StaticArrays.SVector(GI.getexterior(poly_b)))
+ #= Start with poly_b when comparing with holes from poly_a and then switch to poly_a
+ to compare with holes from poly_b. For current_poly, use ext_poly_b to avoid
+ repeating overlapping holes in poly_a and poly_b =#
+ curr_exterior_poly = n_a_holes > 0 ? ext_poly_b : ext_poly_a
+ current_poly = n_a_holes > 0 ? ext_poly_b : poly_a
Loop over all holes in both original polygons
julia
for (i, ih) in enumerate(Iterators.flatten((GI.gethole(poly_a), GI.gethole(poly_b))))
+ in_ext, _, _ = _line_polygon_interactions(ih, curr_exterior_poly; exact, closed_line = true)
+ if !in_ext
+ #= if the hole isn't in the overlapping region between the two polygons, add
+ the hole to the resulting polygon as we know it can't interact with any
+ other holes =#
+ push!(polys[1].geom, ih)
+ else
+ #= if the hole is at least partially in the overlapping region, take the
+ difference of the hole from the polygon it didn't originate from - note that
+ when current_poly is poly_a this includes poly_a holes so overlapping holes
+ between poly_a and poly_b within the overlap are added, in addition to all
+ holes in non-overlapping regions =#
+ h_poly = GI.Polygon(StaticArrays.SVector(ih))
+ new_holes = difference(h_poly, current_poly; target = GI.PolygonTrait())
+ append!(polys[1].geom, (GI.getexterior(new_h) for new_h in new_holes))
+ end
+ if i == n_a_holes
+ curr_exterior_poly = ext_poly_a
+ current_poly = poly_a
+ end
+ end
+ end
+ return
+end
+
+#= Add holes holes to the union of two polygons where one of the original polygons was
+inside of the other. If adding the the holes reveal that the polygons aren't actually
+intersecting, return the original polygons.=#
+function _add_union_holes_contained_polys!(polys, interior_poly, exterior_poly; exact)
+ union_poly = polys[1]
+ ext_int_ring = GI.getexterior(interior_poly)
+ for (i, ih) in enumerate(GI.gethole(exterior_poly))
+ poly_ih = GI.Polygon(StaticArrays.SVector(ih))
+ in_ih, on_ih, out_ih = _line_polygon_interactions(ext_int_ring, poly_ih; exact, closed_line = true)
+ if in_ih # at least part of interior polygon exterior is within the ith hole
+ if !on_ih && !out_ih
+ #= interior polygon is completly within the ith hole - polygons aren't
+ touching and do not actually form a union =#
+ polys[1] = tuples(interior_poly)
+ push!(polys, tuples(exterior_poly))
+ return polys
+ else
+ #= interior polygon is partially within the ith hole - area of interior
+ polygon reduces the size of the hole =#
+ new_holes = difference(poly_ih, interior_poly; target = GI.PolygonTrait())
+ append!(union_poly.geom, (GI.getexterior(new_h) for new_h in new_holes))
+ end
+ else # none of interior polygon exterior is within the ith hole
+ if !out_ih
+ #= interior polygon's exterior is the same as the ith hole - polygons do
+ form a union, but do not overlap so all holes stay in final polygon =#
+ append!(union_poly.geom, Iterators.drop(GI.gethole(exterior_poly), i))
+ append!(union_poly.geom, GI.gethole(interior_poly))
+ return polys
+ else
+ #= interior polygon's exterior is outside of the ith hole - the interior
+ polygon could either be disjoint from the hole, or contain the hole =#
+ ext_int_poly = GI.Polygon(StaticArrays.SVector(ext_int_ring))
+ in_int, _, _ = _line_polygon_interactions(ih, ext_int_poly; exact, closed_line = true)
+ if in_int
+ #= interior polygon contains the hole - overlapping holes between the
+ interior and exterior polygons will be added =#
+ for jh in GI.gethole(interior_poly)
+ poly_jh = GI.Polygon(StaticArrays.SVector(jh))
+ if intersects(poly_ih, poly_jh)
+ new_holes = intersection(poly_ih, poly_jh; target = GI.PolygonTrait())
+ append!(union_poly.geom, (GI.getexterior(new_h) for new_h in new_holes))
+ end
+ end
+ else
+ #= interior polygon and the exterior polygon are disjoint - add the ith
+ hole as it is not covered by the interior polygon =#
+ push!(union_poly.geom, ih)
+ end
+ end
+ end
+ end
+ return
+end
+
+#= Polygon with multipolygon union - note that all sub-polygons of \`multipoly_b\` will be
+included, unioning these sub-polygons with \`poly_a\` where they intersect. Unless specified
+with \`fix_multipoly = nothing\`, \`multipolygon_b\` will be validated using the given (default
+is \`UnionIntersectingPolygons()\`) correction. =#
+function _union(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.PolygonTrait, poly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix multipoly_b to prevent repeated regions in the output
+ multipoly_b = fix_multipoly(multipoly_b)
+ end
+ polys = [tuples(poly_a, T)]
+ for poly_b in GI.getpolygon(multipoly_b)
+ if intersects(polys[1], poly_b)
If polygons intersect and form a new polygon, swap out polygon
julia
new_polys = union(polys[1], poly_b; target)
+ if length(new_polys) > 1 # case where they intersect by just one point
+ push!(polys, tuples(poly_b, T)) # add poly_b to list
+ else
+ polys[1] = new_polys[1]
+ end
+ else
If they don't intersect, poly_b is now a part of the union as its own polygon
julia
push!(polys, tuples(poly_b, T))
+ end
+ end
+ return polys
+end
+
+#= Multipolygon with polygon union is equivalent to taking the union of the poylgon with the
+multipolygon and thus simply switches the order of operations and calls the above method. =#
+_union(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.PolygonTrait, poly_b;
+ kwargs...,
+) where T = union(poly_b, multipoly_a; target, kwargs...)
+
+#= Multipolygon with multipolygon union - note that all of the sub-polygons of \`multipoly_a\`
+and the sub-polygons of \`multipoly_b\` are included and combined together where there are
+intersections. Unless specified with \`fix_multipoly = nothing\`, \`multipolygon_b\` will be
+validated using the given (default is \`UnionIntersectingPolygons()\`) correction. =#
+function _union(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix multipoly_b to prevent repeated regions in the output
+ multipoly_b = fix_multipoly(multipoly_b)
+ fix_multipoly = nothing
+ end
+ multipolys = multipoly_b
+ local polys
+ for poly_a in GI.getpolygon(multipoly_a)
+ polys = union(poly_a, multipolys; target, fix_multipoly)
+ multipolys = GI.MultiPolygon(polys)
+ end
+ return polys
+end
Many type and target combos aren't implemented
julia
function _union(
+ ::TraitTarget{Target}, ::Type{T},
+ trait_a::GI.AbstractTrait, geom_a,
+ trait_b::GI.AbstractTrait, geom_b;
+ kwargs...
+) where {Target,T}
+ throw(ArgumentError("Union between $trait_a and $trait_b with target $Target isn't implemented yet."))
+ return nothing
+end
`,28),p=[h];function t(k,e,r,E,g,y){return a(),i("div",null,p)}const F=s(l,[["render",t]]);export{o as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_clipping_union.md.CTJa5OQM.lean.js b/previews/PR149/assets/source_methods_clipping_union.md.CTJa5OQM.lean.js
new file mode 100644
index 000000000..596dbb317
--- /dev/null
+++ b/previews/PR149/assets/source_methods_clipping_union.md.CTJa5OQM.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Union Polygon Clipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/union.md","filePath":"source/methods/clipping/union.md","lastUpdated":null}'),l={name:"source/methods/clipping/union.md"},h=n("",28),p=[h];function t(k,e,r,E,g,y){return a(),i("div",null,p)}const F=s(l,[["render",t]]);export{o as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_distance.md.u2pOSeLI.js b/previews/PR149/assets/source_methods_distance.md.u2pOSeLI.js
new file mode 100644
index 000000000..b5ecd752d
--- /dev/null
+++ b/previews/PR149/assets/source_methods_distance.md.u2pOSeLI.js
@@ -0,0 +1,181 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/pmneflj.DiwGEg2f.png",t="/GeometryOps.jl/previews/PR149/assets/nkraqub.BwdbZIFa.png",c=JSON.parse('{"title":"Distance and signed distance","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/distance.md","filePath":"source/methods/distance.md","lastUpdated":null}'),k={name:"source/methods/distance.md"},p=n(`
Distance is the distance of a point to another geometry. This is always a positive number. If a point is inside of geometry, so on a curve or inside of a polygon, the distance will be zero. Signed distance is mainly used for polygons and multipolygons. If a point is outside of a geometry, signed distance has the same value as distance. However, points within the geometry have a negative distance representing the distance of a point to the closest boundary. Therefore, for all "non-filled" geometries, like curves, the distance will either be postitive or 0.
To provide an example, consider this rectangle:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+rect = GI.Polygon([[(0,0), (0,1), (1,1), (1,0), (0, 0)]])
+point_in = (0.5, 0.5)
+point_out = (0.5, 1.5)
+f, a, p = poly(collect(GI.getpoint(rect)); axis = (; aspect = DataAspect()))
+scatter!(GI.x(point_in), GI.y(point_in); color = :red)
+scatter!(GI.x(point_out), GI.y(point_out); color = :orange)
+f
This is clearly a rectangle with one point inside and one point outside. The points are both an equal distance to the polygon. The distance to point_in is negative while the distance to point_out is positive.
This is the GeoInterface-compatible implementation. First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Distance and signed distance are only implemented for points to other geometries right now. This could be extended to include distance from other geometries in the future.
The distance calculated is the Euclidean distance using the Pythagorean theorem. Also note that singed_distance only makes sense for "filled-in" shapes, like polygons, so it isn't implemented for curves.
julia
const _DISTANCE_TARGETS = TraitTarget{Union{GI.AbstractPolygonTrait,GI.LineStringTrait,GI.LinearRingTrait,GI.LineTrait,GI.PointTrait}}()
+
+"""
+ distance(point, geom, ::Type{T} = Float64)::T
+
+Calculates the ditance from the geometry \`g1\` to the \`point\`. The distance
+will always be positive or zero.
+
+The method will differ based on the type of the geometry provided:
+ - The distance from a point to a point is just the Euclidean distance
+ between the points.
+ - The distance from a point to a line is the minimum distance from the point
+ to the closest point on the given line.
+ - The distance from a point to a linestring is the minimum distance from the
+ point to the closest segment of the linestring.
+ - The distance from a point to a linear ring is the minimum distance from
+ the point to the closest segment of the linear ring.
+ - The distance from a point to a polygon is zero if the point is within the
+ polygon and otherwise is the minimum distance from the point to an edge of
+ the polygon. This includes edges created by holes.
+ - The distance from a point to a multigeometry or a geometry collection is
+ the minimum distance between the point and any of the sub-geometries.
+
+Result will be of type T, where T is an optional argument with a default value
+of Float64.
+"""
+function distance(
+ geom1, geom2, ::Type{T} = Float64; threaded=false
+) where T<:AbstractFloat
+ distance(GI.trait(geom1), geom1, GI.trait(geom2), geom2, T; threaded)
+end
+function distance(
+ trait1, geom, trait2::GI.PointTrait, point, ::Type{T} = Float64;
+ threaded=false
+) where T<:AbstractFloat
+ distance(trait2, point, trait1, geom, T) # Swap order
+end
+function distance(
+ trait1::GI.PointTrait, point, trait2, geom, ::Type{T} = Float64;
+ threaded=false
+) where T<:AbstractFloat
+ applyreduce(min, _DISTANCE_TARGETS, geom; threaded, init=typemax(T)) do g
+ _distance(T, trait1, point, GI.trait(g), g)
+ end
+end
_distance(::Type{T}, ::GI.PointTrait, point, ::GI.PointTrait, geom) where T =
+ _euclid_distance(T, point, geom)
+_distance(::Type{T}, ::GI.PointTrait, point, ::GI.LineTrait, geom) where T =
+ _distance_line(T, point, GI.getpoint(geom, 1), GI.getpoint(geom, 2))
+_distance(::Type{T}, ::GI.PointTrait, point, ::GI.LineStringTrait, geom) where T =
+ _distance_curve(T, point, geom; close_curve = false)
+_distance(::Type{T}, ::GI.PointTrait, point, ::GI.LinearRingTrait, geom) where T =
+ _distance_curve(T, point, geom; close_curve = true)
Point-Polygon
julia
function _distance(::Type{T}, ::GI.PointTrait, point, ::GI.PolygonTrait, geom) where T
+ within(point, geom) && return zero(T)
+ return _distance_polygon(T, point, geom)
+end
+
+"""
+ signed_distance(point, geom, ::Type{T} = Float64)::T
+
+Calculates the signed distance from the geometry \`geom\` to the given point.
+Points within \`geom\` have a negative signed distance, and points outside of
+\`geom\` have a positive signed distance.
+ - The signed distance from a point to a point, line, linestring, or linear
+ ring is equal to the distance between the two.
+ - The signed distance from a point to a polygon is negative if the point is
+ within the polygon and is positive otherwise. The value of the distance is
+ the minimum distance from the point to an edge of the polygon. This includes
+ edges created by holes.
+ - The signed distance from a point to a multigeometry or a geometry
+ collection is the minimum signed distance between the point and any of the
+ sub-geometries.
+
+Result will be of type T, where T is an optional argument with a default value
+of Float64.
+"""
+function signed_distance(
+ geom1, geom2, ::Type{T} = Float64; threaded=false
+) where T<:AbstractFloat
+ signed_distance(GI.trait(geom1), geom1, GI.trait(geom2), geom2, T; threaded)
+end
+function signed_distance(
+ trait1, geom, trait2::GI.PointTrait, point, ::Type{T} = Float64;
+ threaded=false
+) where T<:AbstractFloat
+ signed_distance(trait2, point, trait1, geom, T; threaded) # Swap order
+end
+function signed_distance(
+ trait1::GI.PointTrait, point, trait2, geom, ::Type{T} = Float64;
+ threaded=false
+) where T<:AbstractFloat
+ applyreduce(min, _DISTANCE_TARGETS, geom; threaded, init=typemax(T)) do g
+ _signed_distance(T, trait1, point, GI.trait(g), g)
+ end
+end
function _signed_distance(
+ ::Type{T}, ptrait::GI.PointTrait, point, gtrait::GI.AbstractGeometryTrait, geom
+) where T
+ _distance(T, ptrait, point, gtrait, geom)
+end
Point-Polygon
julia
function _signed_distance(::Type{T}, ::GI.PointTrait, point, ::GI.PolygonTrait, geom) where T
+ min_dist = _distance_polygon(T, point, geom)
+ return within(point, geom) ? -min_dist : min_dist
negative if point is inside polygon
julia
end
Returns the Euclidean distance between two points.
julia
Base.@propagate_inbounds _euclid_distance(::Type{T}, p1, p2) where T =
+ sqrt(_squared_euclid_distance(T, p1, p2))
Returns the square of the euclidean distance between two points
julia
Base.@propagate_inbounds _squared_euclid_distance(::Type{T}, p1, p2) where T =
+ _squared_euclid_distance(
+ T,
+ GeoInterface.x(p1), GeoInterface.y(p1),
+ GeoInterface.x(p2), GeoInterface.y(p2),
+ )
Returns the Euclidean distance between two points given their x and y values.
julia
Base.@propagate_inbounds _euclid_distance(::Type{T}, x1, y1, x2, y2) where T =
+ sqrt(_squared_euclid_distance(T, x1, y1, x2, y2))
Returns the squared Euclidean distance between two points given their x and y values.
julia
Base.@propagate_inbounds _squared_euclid_distance(::Type{T}, x1, y1, x2, y2) where T =
+ T((x2 - x1)^2 + (y2 - y1)^2)
Returns the minimum distance from point p0 to the line defined by endpoints p1 and p2.
julia
_distance_line(::Type{T}, p0, p1, p2) where T =
+ sqrt(_squared_distance_line(T, p0, p1, p2))
Returns the squared minimum distance from point p0 to the line defined by endpoints p1 and p2.
julia
function _squared_distance_line(::Type{T}, p0, p1, p2) where T
+ x0, y0 = GeoInterface.x(p0), GeoInterface.y(p0)
+ x1, y1 = GeoInterface.x(p1), GeoInterface.y(p1)
+ x2, y2 = GeoInterface.x(p2), GeoInterface.y(p2)
+
+ xfirst, yfirst, xlast, ylast = x1 < x2 ? (x1, y1, x2, y2) : (x2, y2, x1, y1)
+
+ #=
+ Vectors from first point to last point (v) and from first point to point of
+ interest (w) to find the projection of w onto v to find closest point
+ =#
+ v = (xlast - xfirst, ylast - yfirst)
+ w = (x0 - xfirst, y0 - yfirst)
+
+ c1 = sum(w .* v)
+ if c1 <= 0 # p0 is closest to first endpoint
+ return _squared_euclid_distance(T, x0, y0, xfirst, yfirst)
+ end
+
+ c2 = sum(v .* v)
+ if c2 <= c1 # p0 is closest to last endpoint
+ return _squared_euclid_distance(T, x0, y0, xlast, ylast)
+ end
+
+ b2 = c1 / c2 # projection fraction
+ return _squared_euclid_distance(T, x0, y0, xfirst + (b2 * v[1]), yfirst + (b2 * v[2]))
+end
Returns the minimum distance from the given point to the given curve. If close_curve is true, make sure to include the edge from the first to last point of the curve, even if it isn't explicitly repeated.
julia
function _distance_curve(::Type{T}, point, curve; close_curve = false) where T
see if linear ring has explicitly repeated last point in coordinates
Returns the minimum distance from the given point to an edge of the given polygon, including from edges created by holes. Assumes polygon isn't filled and treats the exterior and each hole as a linear ring.
julia
function _distance_polygon(::Type{T}, point, poly) where T
+ min_dist = _distance_curve(T, point, GI.getexterior(poly); close_curve = true)
+ @inbounds for hole in GI.gethole(poly)
+ dist = _distance_curve(T, point, hole; close_curve = true)
+ min_dist = dist < min_dist ? dist : min_dist
+ end
+ return min_dist
+end
`,54),l=[p];function e(d,E,r,g,y,F){return a(),i("div",null,l)}const C=s(k,[["render",e]]);export{c as __pageData,C as default};
diff --git a/previews/PR149/assets/source_methods_distance.md.u2pOSeLI.lean.js b/previews/PR149/assets/source_methods_distance.md.u2pOSeLI.lean.js
new file mode 100644
index 000000000..033c860c4
--- /dev/null
+++ b/previews/PR149/assets/source_methods_distance.md.u2pOSeLI.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/pmneflj.DiwGEg2f.png",t="/GeometryOps.jl/previews/PR149/assets/nkraqub.BwdbZIFa.png",c=JSON.parse('{"title":"Distance and signed distance","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/distance.md","filePath":"source/methods/distance.md","lastUpdated":null}'),k={name:"source/methods/distance.md"},p=n("",54),l=[p];function e(d,E,r,g,y,F){return a(),i("div",null,l)}const C=s(k,[["render",e]]);export{c as __pageData,C as default};
diff --git a/previews/PR149/assets/source_methods_equals.md.Cobgpr9u.js b/previews/PR149/assets/source_methods_equals.md.Cobgpr9u.js
new file mode 100644
index 000000000..896a7963c
--- /dev/null
+++ b/previews/PR149/assets/source_methods_equals.md.Cobgpr9u.js
@@ -0,0 +1,265 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const l="/GeometryOps.jl/previews/PR149/assets/bbznugt.CgiryX2p.png",y=JSON.parse('{"title":"Equals","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/equals.md","filePath":"source/methods/equals.md","lastUpdated":null}'),t={name:"source/methods/equals.md"},h=n(`
The equals function checks if two geometries are equal. They are equal if they share the same set of points and edges to define the same shape.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.LineString([(0.0, 0.0), (0.0, 10.0)])
+l2 = GI.LineString([(0.0, -10.0), (0.0, 3.0)])
+f, a, p = lines(GI.getpoint(l1), color = :blue)
+scatter!(GI.getpoint(l1), color = :blue)
+lines!(GI.getpoint(l2), color = :orange)
+scatter!(GI.getpoint(l2), color = :orange)
+f
We can see that the two lines do not share a commen set of points and edges in the plot, so they are not equal:
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Note that while we need the same set of points and edges, they don't need to be provided in the same order for polygons. For for example, we need the same set points for two multipoints to be equal, but they don't have to be saved in the same order. The winding order also doesn't have to be the same to represent the same geometry. This requires checking every point against every other point in the two geometries we are comparing. Also, some geometries must be "closed" like polygons and linear rings. These will be assumed to be closed, even if they don't have a repeated last point explicity written in the coordinates. Additionally, geometries and multi-geometries can be equal if the multi-geometry only includes that single geometry.
julia
"""
+ equals(geom1, geom2)::Bool
+
+Compare two Geometries return true if they are the same geometry.
+
+# Examples
+\`\`\`jldoctest
+import GeometryOps as GO, GeoInterface as GI
+poly1 = GI.Polygon([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+poly2 = GI.Polygon([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+
+GO.equals(poly1, poly2)
output
julia
true
+\`\`\`
+"""
+equals(geom_a, geom_b) = equals(
+ GI.trait(geom_a), geom_a,
+ GI.trait(geom_b), geom_b,
+)
+
+"""
+ equals(::T, geom_a, ::T, geom_b)::Bool
+
+Two geometries of the same type, which don't have a equals function to dispatch
+off of should throw an error.
+"""
+equals(::T, geom_a, ::T, geom_b) where T = error("Cant compare $T yet")
+
+"""
+ equals(trait_a, geom_a, trait_b, geom_b)
+
+Two geometries which are not of the same type cannot be equal so they always
+return false.
+"""
+equals(trait_a, geom_a, trait_b, geom_b) = false
+
+"""
+ equals(::GI.PointTrait, p1, ::GI.PointTrait, p2)::Bool
+
+Two points are the same if they have the same x and y (and z if 3D) coordinates.
+"""
+function equals(::GI.PointTrait, p1, ::GI.PointTrait, p2)
+ GI.ncoord(p1) == GI.ncoord(p2) || return false
+ GI.x(p1) == GI.x(p2) || return false
+ GI.y(p1) == GI.y(p2) || return false
+ if GI.is3d(p1)
+ GI.z(p1) == GI.z(p2) || return false
+ end
+ return true
+end
+
+"""
+ equals(::GI.PointTrait, p1, ::GI.MultiPointTrait, mp2)::Bool
+
+A point and a multipoint are equal if the multipoint is composed of a single
+point that is equivalent to the given point.
+"""
+function equals(::GI.PointTrait, p1, ::GI.MultiPointTrait, mp2)
+ GI.npoint(mp2) == 1 || return false
+ return equals(p1, GI.getpoint(mp2, 1))
+end
+
+"""
+ equals(::GI.MultiPointTrait, mp1, ::GI.PointTrait, p2)::Bool
+
+A point and a multipoint are equal if the multipoint is composed of a single
+point that is equivalent to the given point.
+"""
+equals(trait1::GI.MultiPointTrait, mp1, trait2::GI.PointTrait, p2) =
+ equals(trait2, p2, trait1, mp1)
+
+"""
+ equals(::GI.MultiPointTrait, mp1, ::GI.MultiPointTrait, mp2)::Bool
+
+Two multipoints are equal if they share the same set of points.
+"""
+function equals(::GI.MultiPointTrait, mp1, ::GI.MultiPointTrait, mp2)
+ GI.npoint(mp1) == GI.npoint(mp2) || return false
+ for p1 in GI.getpoint(mp1)
+ has_match = false # if point has a matching point in other multipoint
+ for p2 in GI.getpoint(mp2)
+ if equals(p1, p2)
+ has_match = true
+ break
+ end
+ end
+ has_match || return false # if no matching point, can't be equal
+ end
+ return true # all points had a match
+end
+
+"""
+ _equals_curves(c1, c2, closed_type1, closed_type2)::Bool
+
+Two curves are equal if they share the same set of point, representing the same
+geometry. Both curves must must be composed of the same set of points, however,
+they do not have to wind in the same direction, or start on the same point to be
+equivalent.
+Inputs:
+ c1 first geometry
+ c2 second geometry
+ closed_type1::Bool true if c1 is closed by definition (polygon, linear ring)
+ closed_type2::Bool true if c2 is closed by definition (polygon, linear ring)
+"""
+function _equals_curves(c1, c2, closed_type1, closed_type2)
Check all remaining points are the same wrapping around line
julia
jstep = same_direction ? 1 : -1
+ for i in 2:n1
+ ip = GI.getpoint(c1, i)
+ j = jstart + (i - 1) * jstep
+ j += (0 < j <= n2) ? 0 : (n2 * -jstep)
+ jp = GI.getpoint(c2, j)
+ equals(ip, jp) || return false
+ end
+ return true
+end
+
+"""
+ equals(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l2,
+ )::Bool
+
+Two lines/linestrings are equal if they share the same set of points going
+along the curve. Note that lines/linestrings aren't closed by defintion.
+"""
+equals(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l2,
+) = _equals_curves(l1, l2, false, false)
+
+"""
+ equals(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l1,
+ ::GI.LinearRingTrait, l2,
+ )::Bool
+
+A line/linestring and a linear ring are equal if they share the same set of
+points going along the curve. Note that lines aren't closed by defintion, but
+rings are, so the line must have a repeated last point to be equal
+"""
+equals(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l1,
+ ::GI.LinearRingTrait, l2,
+) = _equals_curves(l1, l2, false, true)
+
+"""
+ equals(
+ ::GI.LinearRingTrait, l1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l2,
+ )::Bool
+
+A linear ring and a line/linestring are equal if they share the same set of
+points going along the curve. Note that lines aren't closed by defintion, but
+rings are, so the line must have a repeated last point to be equal
+"""
+equals(
+ ::GI.LinearRingTrait, l1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l2,
+) = _equals_curves(l1, l2, true, false)
+
+"""
+ equals(
+ ::GI.LinearRingTrait, l1,
+ ::GI.LinearRingTrait, l2,
+ )::Bool
+
+Two linear rings are equal if they share the same set of points going along the
+curve. Note that rings are closed by definition, so they can have, but don't
+need, a repeated last point to be equal.
+"""
+equals(
+ ::GI.LinearRingTrait, l1,
+ ::GI.LinearRingTrait, l2,
+) = _equals_curves(l1, l2, true, true)
+
+"""
+ equals(::GI.PolygonTrait, geom_a, ::GI.PolygonTrait, geom_b)::Bool
+
+Two polygons are equal if they share the same exterior edge and holes.
+"""
+function equals(::GI.PolygonTrait, geom_a, ::GI.PolygonTrait, geom_b)
Check if exterior is equal
julia
_equals_curves(
+ GI.getexterior(geom_a), GI.getexterior(geom_b),
+ true, true, # linear rings are closed by definition
+ ) || return false
for ihole in GI.gethole(geom_a)
+ has_match = false
+ for jhole in GI.gethole(geom_b)
+ if _equals_curves(
+ ihole, jhole,
+ true, true, # linear rings are closed by definition
+ )
+ has_match = true
+ break
+ end
+ end
+ has_match || return false
+ end
+ return true
+end
+
+"""
+ equals(::GI.PolygonTrait, geom_a, ::GI.MultiPolygonTrait, geom_b)::Bool
+
+A polygon and a multipolygon are equal if the multipolygon is composed of a
+single polygon that is equivalent to the given polygon.
+"""
+function equals(::GI.PolygonTrait, geom_a, ::MultiPolygonTrait, geom_b)
+ GI.npolygon(geom_b) == 1 || return false
+ return equals(geom_a, GI.getpolygon(geom_b, 1))
+end
+
+"""
+ equals(::GI.MultiPolygonTrait, geom_a, ::GI.PolygonTrait, geom_b)::Bool
+
+A polygon and a multipolygon are equal if the multipolygon is composed of a
+single polygon that is equivalent to the given polygon.
+"""
+equals(trait_a::GI.MultiPolygonTrait, geom_a, trait_b::PolygonTrait, geom_b) =
+ equals(trait_b, geom_b, trait_a, geom_a)
+
+"""
+ equals(::GI.PolygonTrait, geom_a, ::GI.PolygonTrait, geom_b)::Bool
+
+Two multipolygons are equal if they share the same set of polygons.
+"""
+function equals(::GI.MultiPolygonTrait, geom_a, ::GI.MultiPolygonTrait, geom_b)
for poly_a in GI.getpolygon(geom_a)
+ has_match = false
+ for poly_b in GI.getpolygon(geom_b)
+ if equals(poly_a, poly_b)
+ has_match = true
+ break
+ end
+ end
+ has_match || return false
+ end
+ return true
+end
`,47),p=[h];function e(k,r,d,g,E,F){return a(),i("div",null,p)}const c=s(t,[["render",e]]);export{y as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_equals.md.Cobgpr9u.lean.js b/previews/PR149/assets/source_methods_equals.md.Cobgpr9u.lean.js
new file mode 100644
index 000000000..495eb958e
--- /dev/null
+++ b/previews/PR149/assets/source_methods_equals.md.Cobgpr9u.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const l="/GeometryOps.jl/previews/PR149/assets/bbznugt.CgiryX2p.png",y=JSON.parse('{"title":"Equals","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/equals.md","filePath":"source/methods/equals.md","lastUpdated":null}'),t={name:"source/methods/equals.md"},h=n("",47),p=[h];function e(k,r,d,g,E,F){return a(),i("div",null,p)}const c=s(t,[["render",e]]);export{y as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_contains.md.C34_xZ8I.js b/previews/PR149/assets/source_methods_geom_relations_contains.md.C34_xZ8I.js
new file mode 100644
index 000000000..d2accf9c8
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_contains.md.C34_xZ8I.js
@@ -0,0 +1,33 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const t="/GeometryOps.jl/previews/PR149/assets/dvvvcck._0R9BbFk.png",y=JSON.parse('{"title":"Contains","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/contains.md","filePath":"source/methods/geom_relations/contains.md","lastUpdated":null}'),e={name:"source/methods/geom_relations/contains.md"},h=n(`
The contains function checks if a given geometry completly contains another geometry, or in other words, that the second geometry is completly within the first. This requires that the two interiors intersect and that the interior and boundary of the second geometry is not in the exterior of the first geometry.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.LineString([(0.0, 0.0), (1.0, 0.0), (0.0, 0.1)])
+l2 = GI.LineString([(0.25, 0.0), (0.75, 0.0)])
+f, a, p = lines(GI.getpoint(l1), color = :blue)
+scatter!(GI.getpoint(l1), color = :blue)
+lines!(GI.getpoint(l2), color = :orange)
+scatter!(GI.getpoint(l2), color = :orange)
+f
We can see that all of the points and edges of l2 are within l1, so l1 contains l2. However, l2 does not contain l1.
This is the GeoInterface-compatible implementation.
Given that contains is the exact opposite of within, we simply pass the two inputs variables, swapped in order, to within.
julia
"""
+ contains(g1::AbstractGeometry, g2::AbstractGeometry)::Bool
+
+Return true if the second geometry is completely contained by the first
+geometry. The interiors of both geometries must intersect and the interior and
+boundary of the secondary (g2) must not intersect the exterior of the first
+(g1).
+
+\`contains\` returns the exact opposite result of \`within\`.
+
+# Examples
+
+\`\`\`jldoctest
+import GeometryOps as GO, GeoInterface as GI
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = GI.Point((1, 2))
+
+GO.contains(line, point)
`,18),l=[h];function p(k,r,o,d,g,E){return a(),i("div",null,l)}const F=s(e,[["render",p]]);export{y as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_contains.md.C34_xZ8I.lean.js b/previews/PR149/assets/source_methods_geom_relations_contains.md.C34_xZ8I.lean.js
new file mode 100644
index 000000000..853591835
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_contains.md.C34_xZ8I.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const t="/GeometryOps.jl/previews/PR149/assets/dvvvcck._0R9BbFk.png",y=JSON.parse('{"title":"Contains","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/contains.md","filePath":"source/methods/geom_relations/contains.md","lastUpdated":null}'),e={name:"source/methods/geom_relations/contains.md"},h=n("",18),l=[h];function p(k,r,o,d,g,E){return a(),i("div",null,l)}const F=s(e,[["render",p]]);export{y as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_coveredby.md.DTBr48oT.js b/previews/PR149/assets/source_methods_geom_relations_coveredby.md.DTBr48oT.js
new file mode 100644
index 000000000..560ec3d00
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_coveredby.md.DTBr48oT.js
@@ -0,0 +1,183 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const e="/GeometryOps.jl/previews/PR149/assets/agabzyz.DC3TvBOO.png",c=JSON.parse('{"title":"CoveredBy","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/coveredby.md","filePath":"source/methods/geom_relations/coveredby.md","lastUpdated":null}'),l={name:"source/methods/geom_relations/coveredby.md"},h=n(`
The coveredby function checks if one geometry is covered by another geometry. This is an extension of within that does not require the interiors of the two geometries to intersect, but still does require that the interior and boundary of the first geometry isn't outside of the second geometry.
To provide an example, consider this point and line:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+p1 = (0.0, 0.0)
+l1 = GI.Line([p1, (1.0, 1.0)])
+f, a, p = lines(GI.getpoint(l1))
+scatter!(p1, color = :red)
+f
As we can see, p1 is on the endpoint of l1. This means it is not within, but it does meet the definition of coveredby.
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait.
Each of these calls a method in the geom_geom_processors file. The methods in this file determine if the given geometries meet a set of criteria. For the coveredby function and arguments g1 and g2, this criteria is as follows: - points of g1 are allowed to be in the interior of g2 (either through overlap or crossing for lines) - points of g1 are allowed to be on the boundary of g2 - points of g1 are not allowed to be in the exterior of g2 - no points of g1 are required to be in the interior of g2 - no points of g1 are required to be on the boundary of g2 - no points of g1 are required to be in the exterior of g2
The code for the specific implementations is in the geom_geom_processors file.
julia
const COVEREDBY_ALLOWS = (in_allow = true, on_allow = true, out_allow = false)
+const COVEREDBY_CURVE_ALLOWS = (over_allow = true, cross_allow = true, on_allow = true, out_allow = false)
+const COVEREDBY_CURVE_REQUIRES = (in_require = false, on_require = false, out_require = false)
+const COVEREDBY_POLYGON_REQUIRES = (in_require = true, on_require = false, out_require = false,)
+const COVEREDBY_EXACT = (exact = _False(),)
+
+"""
+ coveredby(g1, g2)::Bool
+
+Return \`true\` if the first geometry is completely covered by the second
+geometry. The interior and boundary of the primary geometry (g1) must not
+intersect the exterior of the secondary geometry (g2).
+
+Furthermore, \`coveredby\` returns the exact opposite result of \`covers\`. They are
+equivalent with the order of the arguments swapped.
+
+# Examples
+\`\`\`jldoctest setup=:(using GeometryOps, GeometryBasics)
+import GeometryOps as GO, GeoInterface as GI
+p1 = GI.Point(0.0, 0.0)
+p2 = GI.Point(1.0, 1.0)
+l1 = GI.Line([p1, p2])
+
+GO.coveredby(p1, l1)
#= Linestring is coveredby a line if all interior and boundary points of the
+first line are on the interior/boundary points of the second line. =#
+_coveredby(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ COVEREDBY_CURVE_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = false,
+ closed_curve = false,
+)
+
+#= Linestring is coveredby a ring if all interior and boundary points of the
+line are on the edges of the ring. =#
+_coveredby(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ COVEREDBY_CURVE_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = false,
+ closed_curve = true,
+)
+
+#= Linestring is coveredby a polygon if all interior and boundary points of the
+line are in the polygon interior or on its edges, inlcuding hole edges. =#
+_coveredby(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ COVEREDBY_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = false,
+)
#= Linearring is covered by a line if all vertices and edges of the ring are on
+the edges and vertices of the line. =#
+_coveredby(
+ ::GI.LinearRingTrait, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ COVEREDBY_CURVE_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = true,
+ closed_curve = false,
+)
+
+#= Linearring is covered by another linear ring if all vertices and edges of the
+first ring are on the edges/vertices of the second ring. =#
+_coveredby(
+ ::GI.LinearRingTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ COVEREDBY_CURVE_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = true,
+ closed_curve = true,
+)
+
+#= Linearring is coveredby a polygon if all vertices and edges of the ring are
+in the polygon interior or on the polygon edges, inlcuding hole edges. =#
+_coveredby(
+ ::GI.LinearRingTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ COVEREDBY_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = true,
+)
#= Polygon is covered by another polygon if if the interior and edges of the
+first polygon are in the second polygon interior or on polygon edges, including
+hole edges.=#
+_coveredby(
+ ::GI.PolygonTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _polygon_polygon_process(
+ g1, g2;
+ COVEREDBY_ALLOWS...,
+ COVEREDBY_POLYGON_REQUIRES...,
+ COVEREDBY_EXACT...,
+)
#= Geometry is covered by a multi-geometry or a collection if one of the elements
+of the collection cover the geometry. =#
+function _coveredby(
+ ::Union{GI.PointTrait, GI.AbstractCurveTrait, GI.PolygonTrait}, g1,
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g2,
+)
+ for sub_g2 in GI.getgeom(g2)
+ coveredby(g1, sub_g2) && return true
+ end
+ return false
+end
#= Multi-geometry or a geometry collection is covered by a geometry if all
+elements of the collection are covered by the geometry. =#
+function _coveredby(
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g1,
+ ::GI.AbstractGeometryTrait, g2,
+)
+ for sub_g1 in GI.getgeom(g1)
+ !coveredby(sub_g1, g2) && return false
+ end
+ return true
+end
`,45),t=[h];function p(k,r,E,d,g,o){return a(),i("div",null,t)}const F=s(l,[["render",p]]);export{c as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_coveredby.md.DTBr48oT.lean.js b/previews/PR149/assets/source_methods_geom_relations_coveredby.md.DTBr48oT.lean.js
new file mode 100644
index 000000000..7e41b1226
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_coveredby.md.DTBr48oT.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const e="/GeometryOps.jl/previews/PR149/assets/agabzyz.DC3TvBOO.png",c=JSON.parse('{"title":"CoveredBy","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/coveredby.md","filePath":"source/methods/geom_relations/coveredby.md","lastUpdated":null}'),l={name:"source/methods/geom_relations/coveredby.md"},h=n("",45),t=[h];function p(k,r,E,d,g,o){return a(),i("div",null,t)}const F=s(l,[["render",p]]);export{c as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_covers.md.CKCbYXnL.js b/previews/PR149/assets/source_methods_geom_relations_covers.md.CKCbYXnL.js
new file mode 100644
index 000000000..51e9bf63d
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_covers.md.CKCbYXnL.js
@@ -0,0 +1,33 @@
+import{_ as s,c as i,o as a,a6 as e}from"./chunks/framework.CDOaXZPW.js";const n="/GeometryOps.jl/previews/PR149/assets/agabzyz.DC3TvBOO.png",y=JSON.parse('{"title":"Covers","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/covers.md","filePath":"source/methods/geom_relations/covers.md","lastUpdated":null}'),t={name:"source/methods/geom_relations/covers.md"},p=e(`
The covers function checks if a given geometry completly covers another geometry. For this to be true, the "contained" geometry's interior and boundaries must be covered by the "covering" geometry's interior and boundaries. The interiors do not need to overlap.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+p1 = (0.0, 0.0)
+p2 = (1.0, 1.0)
+l1 = GI.Line([p1, p2])
+
+f, a, p = lines(GI.getpoint(l1))
+scatter!(p1, color = :red)
+f
This is the GeoInterface-compatible implementation.
Given that covers is the exact opposite of coveredby, we simply pass the two inputs variables, swapped in order, to coveredby.
julia
"""
+ covers(g1::AbstractGeometry, g2::AbstractGeometry)::Bool
+
+Return true if the first geometry is completely covers the second geometry,
+The exterior and boundary of the second geometry must not be outside of the
+interior and boundary of the first geometry. However, the interiors need not
+intersect.
+
+\`covers\` returns the exact opposite result of \`coveredby\`.
+
+# Examples
+
+\`\`\`jldoctest
+import GeometryOps as GO, GeoInterface as GI
+l1 = GI.LineString([(1.0, 1.0), (1.0, 2.0), (1.0, 3.0), (1.0, 4.0)])
+l2 = GI.LineString([(1.0, 1.0), (1.0, 2.0)])
+
+GO.covers(l1, l2)
`,17),l=[p];function h(k,r,o,d,c,g){return a(),i("div",null,l)}const u=s(t,[["render",h]]);export{y as __pageData,u as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_covers.md.CKCbYXnL.lean.js b/previews/PR149/assets/source_methods_geom_relations_covers.md.CKCbYXnL.lean.js
new file mode 100644
index 000000000..fb862c92f
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_covers.md.CKCbYXnL.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as e}from"./chunks/framework.CDOaXZPW.js";const n="/GeometryOps.jl/previews/PR149/assets/agabzyz.DC3TvBOO.png",y=JSON.parse('{"title":"Covers","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/covers.md","filePath":"source/methods/geom_relations/covers.md","lastUpdated":null}'),t={name:"source/methods/geom_relations/covers.md"},p=e("",17),l=[p];function h(k,r,o,d,c,g){return a(),i("div",null,l)}const u=s(t,[["render",h]]);export{y as __pageData,u as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_crosses.md.CKZ4bXLi.js b/previews/PR149/assets/source_methods_geom_relations_crosses.md.CKZ4bXLi.js
new file mode 100644
index 000000000..c1f0281a4
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_crosses.md.CKZ4bXLi.js
@@ -0,0 +1,120 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Crossing checks","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/crosses.md","filePath":"source/methods/geom_relations/crosses.md","lastUpdated":null}'),l={name:"source/methods/geom_relations/crosses.md"},p=n(`
"""
+ crosses(geom1, geom2)::Bool
+
+Return \`true\` if the intersection results in a geometry whose dimension is one less than
+the maximum dimension of the two source geometries and the intersection set is interior to
+both source geometries.
+
+TODO: broken
+
+# Examples
+\`\`\`julia
+import GeoInterface as GI, GeometryOps as GO
TODO: Add working example
julia
\`\`\`
+"""
+crosses(g1, g2)::Bool = crosses(trait(g1), g1, trait(g2), g2)::Bool
+crosses(t1::FeatureTrait, g1, t2, g2)::Bool = crosses(GI.geometry(g1), g2)
+crosses(t1, g1, t2::FeatureTrait, g2)::Bool = crosses(g1, geometry(g2))
+crosses(::MultiPointTrait, g1, ::LineStringTrait, g2)::Bool = multipoint_crosses_line(g1, g2)
+crosses(::MultiPointTrait, g1, ::PolygonTrait, g2)::Bool = multipoint_crosses_poly(g1, g2)
+crosses(::LineStringTrait, g1, ::MultiPointTrait, g2)::Bool = multipoint_crosses_lines(g2, g1)
+crosses(::LineStringTrait, g1, ::PolygonTrait, g2)::Bool = line_crosses_poly(g1, g2)
+crosses(::LineStringTrait, g1, ::LineStringTrait, g2)::Bool = line_crosses_line(g1, g2)
+crosses(::PolygonTrait, g1, ::MultiPointTrait, g2)::Bool = multipoint_crosses_poly(g2, g1)
+crosses(::PolygonTrait, g1, ::LineStringTrait, g2)::Bool = line_crosses_poly(g2, g1)
+
+function multipoint_crosses_line(geom1, geom2)
+ int_point = false
+ ext_point = false
+ i = 1
+ np2 = GI.npoint(geom2)
+
+ while i < GI.npoint(geom1) && !int_point && !ext_point
+ for j in 1:GI.npoint(geom2) - 1
+ exclude_boundary = (j === 1 || j === np2 - 2) ? :none : :both
+ if _point_on_segment(GI.getpoint(geom1, i), (GI.getpoint(geom2, j), GI.getpoint(geom2, j + 1)); exclude_boundary)
+ int_point = true
+ else
+ ext_point = true
+ end
+ end
+ i += 1
+ end
+ return int_point && ext_point
+end
+
+function line_crosses_line(line1, line2)
+ np2 = GI.npoint(line2)
+ if GeometryOps.intersects(line1, line2)
+ for i in 1:GI.npoint(line1) - 1
+ for j in 1:GI.npoint(line2) - 1
+ exclude_boundary = (j === 1 || j === np2 - 2) ? :none : :both
+ pa = GI.getpoint(line1, i)
+ pb = GI.getpoint(line1, i + 1)
+ p = GI.getpoint(line2, j)
+ _point_on_segment(p, (pa, pb); exclude_boundary) && return true
+ end
+ end
+ end
+ return false
+end
+
+function line_crosses_poly(line, poly)
+ for l in flatten(AbstractCurveTrait, poly)
+ intersects(line, l) && return true
+ end
+ return false
+end
+
+function multipoint_crosses_poly(mp, poly)
+ int_point = false
+ ext_point = false
+
+ for p in GI.getpoint(mp)
+ if _point_polygon_process(
+ p, poly;
+ in_allow = true, on_allow = true, out_allow = false, exact = _False()
+ )
+ int_point = true
+ else
+ ext_point = true
+ end
+ int_point && ext_point && return true
+ end
+ return false
+end
+
+#= TODO: Once crosses is swapped over to use the geom relations workflow, can
+delete these helpers. =#
+
+function _point_on_segment(point, (start, stop); exclude_boundary::Symbol=:none)::Bool
+ x, y = GI.x(point), GI.y(point)
+ x1, y1 = GI.x(start), GI.y(start)
+ x2, y2 = GI.x(stop), GI.y(stop)
+
+ dxc = x - x1
+ dyc = y - y1
+ dx1 = x2 - x1
+ dy1 = y2 - y1
`,10),h=[p];function t(k,e,r,E,g,d){return a(),i("div",null,h)}const o=s(l,[["render",t]]);export{y as __pageData,o as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_crosses.md.CKZ4bXLi.lean.js b/previews/PR149/assets/source_methods_geom_relations_crosses.md.CKZ4bXLi.lean.js
new file mode 100644
index 000000000..65ced78ec
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_crosses.md.CKZ4bXLi.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Crossing checks","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/crosses.md","filePath":"source/methods/geom_relations/crosses.md","lastUpdated":null}'),l={name:"source/methods/geom_relations/crosses.md"},p=n("",10),h=[p];function t(k,e,r,E,g,d){return a(),i("div",null,h)}const o=s(l,[["render",t]]);export{y as __pageData,o as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_disjoint.md.XDbUfGD6.js b/previews/PR149/assets/source_methods_geom_relations_disjoint.md.XDbUfGD6.js
new file mode 100644
index 000000000..9ee2f77fa
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_disjoint.md.XDbUfGD6.js
@@ -0,0 +1,178 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const t="/GeometryOps.jl/previews/PR149/assets/nqatpgs.C3SxJ3x-.png",c=JSON.parse('{"title":"Disjoint","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/disjoint.md","filePath":"source/methods/geom_relations/disjoint.md","lastUpdated":null}'),h={name:"source/methods/geom_relations/disjoint.md"},l=n(`
The disjoint function checks if one geometry is outside of another geometry, without sharing any boundaries or interiors.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.LineString([(0.0, 0.0), (1.0, 0.0), (0.0, 0.1)])
+l2 = GI.LineString([(2.0, 0.0), (2.75, 0.0)])
+f, a, p = lines(GI.getpoint(l1), color = :blue)
+scatter!(GI.getpoint(l1), color = :blue)
+lines!(GI.getpoint(l2), color = :orange)
+scatter!(GI.getpoint(l2), color = :orange)
+f
We can see that none of the edges or vertices of l1 interact with l2 so they are disjoint.
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait.
Each of these calls a method in the geom_geom_processors file. The methods in this file determine if the given geometries meet a set of criteria. For the disjoint function and arguments g1 and g2, this criteria is as follows: - points of g1 are not allowed to be in the interior of g2 - points of g1 are not allowed to be on the boundary of g2 - points of g1 are allowed to be in the exterior of g2 - no points required to be in the interior of g2 - no points of g1 are required to be on the boundary of g2 - no points of g1 are required to be in the exterior of g2
The code for the specific implementations is in the geom_geom_processors file.
julia
const DISJOINT_ALLOWS = (in_allow = false, on_allow = false, out_allow = true)
+const DISJOINT_CURVE_ALLOWS = (over_allow = false, cross_allow = false, on_allow = false, out_allow = true)
+const DISJOINT_REQUIRES = (in_require = false, on_require = false, out_require = false)
+const DISJOINT_EXACT = (exact = _False(),)
+
+"""
+ disjoint(geom1, geom2)::Bool
+
+Return \`true\` if the first geometry is disjoint from the second geometry.
+
+Return \`true\` if the first geometry is disjoint from the second geometry. The
+interiors and boundaries of both geometries must not intersect.
+
+# Examples
+\`\`\`jldoctest setup=:(using GeometryOps, GeoInterface)
+import GeometryOps as GO, GeoInterface as GI
+
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = (2, 2)
+GO.disjoint(point, line)
Point is disjoint from a linearring if it is not on the ring's edges/vertices.
julia
_disjoint(
+ ::GI.PointTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = _point_curve_process(
+ g1, g2;
+ DISJOINT_ALLOWS...,
+ closed_curve = true,
+)
+
+#= Point is disjoint from a polygon if it is not on any edges, vertices, or
+within the polygon's interior. =#
+_disjoint(
+ ::GI.PointTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _point_polygon_process(
+ g1, g2;
+ DISJOINT_ALLOWS...,
+ DISJOINT_EXACT...,
+)
+
+#= Geometry is disjoint from a point if the point is not in the interior or on
+the boundary of the geometry. =#
+_disjoint(
+ trait1::Union{GI.AbstractCurveTrait, GI.PolygonTrait}, g1,
+ trait2::GI.PointTrait, g2,
+) = _disjoint(trait2, g2, trait1, g1)
#= Linestring is disjoint from another line if they do not share any interior
+edge/vertex points or boundary points. =#
+_disjoint(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ DISJOINT_CURVE_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+ closed_line = false,
+ closed_curve = false,
+)
+
+#= Linestring is disjoint from a linearring if they do not share any interior
+edge/vertex points or boundary points. =#
+_disjoint(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ DISJOINT_CURVE_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+ closed_line = false,
+ closed_curve = true,
+)
+
+#= Linestring is disjoint from a polygon if the interior and boundary points of
+the line are not in the polygon's interior or on the polygon's boundary. =#
+_disjoint(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ DISJOINT_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+ closed_line = false,
+)
+
+#= Geometry is disjoint from a linestring if the line's interior and boundary
+points don't intersect with the geometrie's interior and boundary points. =#
+_disjoint(
+ trait1::Union{GI.LinearRingTrait, GI.PolygonTrait}, g1,
+ trait2::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _disjoint(trait2, g2, trait1, g1)
#= Linearrings is disjoint from another linearring if they do not share any
+interior edge/vertex points or boundary points.=#
+_disjoint(
+ ::GI.LinearRingTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ DISJOINT_CURVE_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+ closed_line = true,
+ closed_curve = true,
+)
+
+#= Linearring is disjoint from a polygon if the interior and boundary points of
+the ring are not in the polygon's interior or on the polygon's boundary. =#
+_disjoint(
+ ::GI.LinearRingTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ DISJOINT_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+ closed_line = true,
+)
#= Polygon is disjoint from another polygon if they do not share any edges or
+vertices and if their interiors do not intersect, excluding any holes. =#
+_disjoint(
+ ::GI.PolygonTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _polygon_polygon_process(
+ g1, g2;
+ DISJOINT_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+)
#= Geometry is disjoint from a multi-geometry or a collection if all of the
+elements of the collection are disjoint from the geometry. =#
+function _disjoint(
+ ::Union{GI.PointTrait, GI.AbstractCurveTrait, GI.PolygonTrait}, g1,
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g2,
+)
+ for sub_g2 in GI.getgeom(g2)
+ !disjoint(g1, sub_g2) && return false
+ end
+ return true
+end
#= Multi-geometry or a geometry collection is covered by a geometry if all
+elements of the collection are covered by the geometry. =#
+function _disjoint(
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g1,
+ ::GI.AbstractGeometryTrait, g2,
+)
+ for sub_g1 in GI.getgeom(g1)
+ !disjoint(sub_g1, g2) && return false
+ end
+ return true
+end
`,39),p=[l];function k(e,r,E,g,d,o){return a(),i("div",null,p)}const F=s(h,[["render",k]]);export{c as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_disjoint.md.XDbUfGD6.lean.js b/previews/PR149/assets/source_methods_geom_relations_disjoint.md.XDbUfGD6.lean.js
new file mode 100644
index 000000000..39b642403
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_disjoint.md.XDbUfGD6.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const t="/GeometryOps.jl/previews/PR149/assets/nqatpgs.C3SxJ3x-.png",c=JSON.parse('{"title":"Disjoint","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/disjoint.md","filePath":"source/methods/geom_relations/disjoint.md","lastUpdated":null}'),h={name:"source/methods/geom_relations/disjoint.md"},l=n("",39),p=[l];function k(e,r,E,g,d,o){return a(),i("div",null,p)}const F=s(h,[["render",k]]);export{c as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_geom_geom_processors.md.CXTtFMWr.js b/previews/PR149/assets/source_methods_geom_relations_geom_geom_processors.md.CXTtFMWr.js
new file mode 100644
index 000000000..66be6a6ae
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_geom_geom_processors.md.CXTtFMWr.js
@@ -0,0 +1,437 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Line-curve interaction","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/geom_geom_processors.md","filePath":"source/methods/geom_relations/geom_geom_processors.md","lastUpdated":null}'),h={name:"source/methods/geom_relations/geom_geom_processors.md"},l=n(`
#= Code is based off of DE-9IM Standards (https://en.wikipedia.org/wiki/DE-9IM)
+and attempts a standardized solution for most of the functions.
+=#
+
+"""
+ Enum PointOrientation
+
+Enum for the orientation of a point with respect to a curve. A point can be
+\`point_in\` the curve, \`point_on\` the curve, or \`point_out\` of the curve.
+"""
+@enum PointOrientation point_in=1 point_on=2 point_out=3
Determines if a point meets the given checks with respect to a curve.
If in_allow is true, the point can be on the curve interior. If on_allow is true, the point can be on the curve boundary. If out_allow is true, the point can be disjoint from the curve.
If the point is in an "allowed" location, return true. Else, return false.
If closed_curve is true, curve is treated as a closed curve where the first and last point are connected by a segment.
julia
function _point_curve_process(
+ point, curve;
+ in_allow, on_allow, out_allow,
+ closed_curve = false,
+)
p_start = GI.getpoint(curve, closed_curve ? n : 1)
+ @inbounds for i in (closed_curve ? 1 : 2):n
+ p_end = GI.getpoint(curve, i)
+ seg_val = _point_segment_orientation(point, p_start, p_end)
+ seg_val == point_in && return in_allow
+ if seg_val == point_on
+ if !closed_curve # if point is on curve endpoints, it is "on"
+ i == 2 && equals(point, p_start) && return on_allow
+ i == n && equals(point, p_end) && return on_allow
+ end
+ return in_allow
+ end
+ p_start = p_end
+ end
+ return out_allow
+end
Determines if a point meets the given checks with respect to a polygon.
If in_allow is true, the point can be within the polygon interior If on_allow is true, the point can be on the polygon boundary. If out_allow is true, the point can be disjoint from the polygon.
If the point is in an "allowed" location, return true. Else, return false.
julia
function _point_polygon_process(
+ point, polygon;
+ in_allow, on_allow, out_allow, exact,
+)
Check interaction of geom with polygon's exterior boundary
If a point is outside, it isn't interacting with any holes
julia
ext_val == point_out && return out_allow
if a point is on an external boundary, it isn't interacting with any holes
julia
ext_val == point_on && return on_allow
If geom is within the polygon, need to check interactions with holes
julia
for hole in GI.gethole(polygon)
+ hole_val = _point_filled_curve_orientation(point, hole; exact)
If a point in in a hole, it is outside of the polygon
julia
hole_val == point_in && return out_allow
If a point in on a hole edge, it is on the edge of the polygon
julia
hole_val == point_on && return on_allow
+ end
Point is within external boundary and on in/on any holes
julia
return in_allow
+end
Determines if a line meets the given checks with respect to a curve.
If over_allow is true, segments of the line and curve can be co-linear. If cross_allow is true, segments of the line and curve can cross. If on_allow is true, endpoints of either the line or curve can intersect a segment of the other geometry. If cross_allow is true, segments of the line and curve can be disjoint.
If in_require is true, the interiors of the line and curve must meet in at least one point. If on_require is true, the bounday of one of the two geometries can meet the interior or boundary of the other geometry in at least one point. If out_require is true, there must be at least one point of the given line that is exterior of the curve.
If the point is in an "allowed" location and meets all requirments, return true. Else, return false.
If closed_line is true, line is treated as a closed line where the first and last point are connected by a segment. Same with closed_curve.
Find next pieces of hinge to see if line and curve cross
julia
l, c = _find_hinge_next_segments(
+ α, β, l_start, l_end, c_start, c_end,
+ i, line, j, curve,
+ )
+ next_val, _, _ = _intersection_point(Float64, l, c; exact)
+ if next_val == line_hinge
+ !cross_allow && return false
+ else
+ !over_allow && return false
+ end
+ end
+ end
+ end
no overlap for a give segment, some of segment must be out of curve
julia
if j == nc
+ !out_allow && return false
+ out_req_met = true
+ end
+ end
+ c_start = c_end # consider next segment of curve
+ if j == nc # move on to next line segment
+ i += 1
+ l_start = l_end
+ end
+ end
+ end
+ return in_req_met && on_req_met && out_req_met
+end
+
+#= If entire segment (le to ls) isn't covered by segment (cs to ce), find remaining section
+part of section outside of cs to ce. If completly covered, increase segment index i. =#
+function _find_new_seg(i, ls, le, cs, ce)
+ break_off = true
+ if _point_segment_orientation(le, cs, ce) != point_out
+ ls = le
+ i += 1
+ elseif !equals(ls, cs) && _point_segment_orientation(cs, ls, le) != point_out
+ ls = cs
+ elseif !equals(ls, ce) && _point_segment_orientation(ce, ls, le) != point_out
+ ls = ce
+ else
+ break_off = false
+ end
+ return i, ls, break_off
+end
+
+#= Find next set of segments needed to determine if given hinge segments cross or not.=#
+function _find_hinge_next_segments(α, β, ls, le, cs, ce, i, line, j, curve)
+ next_seg = if β == 1
+ if α == 1 # hinge at endpoints, so next segment of both is needed
+ ((le, _tuple_point(GI.getpoint(line, i + 1))), (ce, _tuple_point(GI.getpoint(curve, j + 1))))
+ else # hinge at curve endpoint and line interior point, curve next segment needed
+ ((ls, le), (ce, _tuple_point(GI.getpoint(curve, j + 1))))
+ end
+ else # hinge at curve interior point and line endpoint, line next segment needed
+ ((le, _tuple_point(GI.getpoint(line, i + 1))), (cs, ce))
+ end
+ return next_seg
+end
Determines if a line meets the given checks with respect to a polygon.
If in_allow is true, segments of the line can be in the polygon interior. If on_allow is true, segments of the line can be on the polygon's boundary. If out_allow is true, segments of the line can be outside of the polygon.
If in_require is true, the interiors of the line and polygon must meet in at least one point. If on_require is true, the line must have at least one point on the polygon'same boundary. If out_require is true, the line must have at least one point outside of the polygon.
If the point is in an "allowed" location and meets all requirments, return true. Else, return false.
If closed_line is true, line is treated as a closed line where the first and last point are connected by a segment.
for hole in GI.gethole(polygon)
+ in_hole, on_hole, out_hole =_line_filled_curve_interactions(
+ line, hole;
+ exact, closed_line = closed_line,
+ )
+ if in_hole # line in hole is equivalent to being out of polygon
+ !out_allow && return false
+ out_req_met = true
+ end
+ if on_hole # hole bounday is polygon boundary
+ !on_allow && return false
+ on_req_met = true
+ end
+ if !out_hole # entire line is in/on hole, can't be in/on other holes
+ in_curve = false
+ break
+ end
+ end
+ if in_curve # entirely of curve isn't within a hole
+ !in_allow && return false
+ in_req_met = true
+ end
+ return in_req_met && on_req_met && out_req_met
+end
Determines if a polygon meets the given checks with respect to a polygon.
If in_allow is true, the polygon's interiors must intersect. If on_allow is true, the one of the polygon's boundaries must either interact with the other polygon's boundary or interior. If out_allow is true, the first polygon must have interior regions outside of the second polygon.
If in_require is true, the polygon interiors must meet in at least one point. If on_require is true, one of the polygon's must have at least one boundary point in or on the other polygon. If out_require is true, the first polygon must have at least one interior point outside of the second polygon.
If the point is in an "allowed" location and meets all requirments, return true. Else, return false.
!e2_out_h1 && return in_req_met && on_req_met && out_req_met
+ break
+ end
+ end
+ #=
+ poly2 isn't outside of poly1 and isn't in a hole, poly1 interior must
+ interact with poly2 interior
+ =#
+ !in_allow && return false
+ in_req_met = true
If any of poly2 holes are within poly1, part of poly1 is exterior to poly2
julia
for h2 in GI.gethole(poly2)
+ h2_in_p1, h2_on_p1, _ = _line_polygon_interactions(
+ h2, poly1;
+ exact, closed_line = true,
+ )
+ if h2_on_p1
+ !on_allow && return false
+ on_req_met = true
+ end
+ if h2_in_p1
+ !out_allow && return false
+ out_req_met = true
+ end
+ end
+ return in_req_met && on_req_met && out_req_met
+end
Determines if a point is in, on, or out of a segment. If the point is on the segment it is on one of the segments endpoints. If it is in, it is on any other point of the segment. If the point is not on any part of the segment, it is out of the segment.
Point should be an object of point trait and curve should be an object with a linestring or linearring trait.
Can provide values of in, on, and out keywords, which determines return values for each scenario.
julia
function _point_segment_orientation(
+ point, start, stop;
+ in::T = point_in, on::T = point_on, out::T = point_out,
+) where {T}
If point is equal to the segment start or end points
julia
return on
+ else
+ #=
+ Determine if the point is on the segment -> see if vector from segment
+ start to point is parallel to segment and if point is between the
+ segment endpoints
+ =#
+ on_line = _isparallel(Δx_seg, Δy_seg, Δx_pt, Δy_pt)
+ !on_line && return out
+ between_endpoints =
+ (x2 > x1 ? x1 <= x <= x2 : x2 <= x <= x1) &&
+ (y2 > y1 ? y1 <= y <= y2 : y2 <= y <= y1)
+ !between_endpoints && return out
+ end
+ return in
+end
Determine if point is in, on, or out of a closed curve, which includes the space enclosed by the closed curve.
In means the point is within the closed curve (excluding edges and vertices). On means the point is on an edge or a vertex of the closed curve. Out means the point is outside of the closed curve.
Point should be an object of point trait and curve should be an object with a linestring or linearring trait, that is assumed to be closed, regardless of repeated last point.
Can provide values of in, on, and out keywords, which determines return values for each scenario.
Note that this uses the Algorithm by Hao and Sun (2018): https://doi.org/10.3390/sym10100477 Paper seperates orientation of point and edge into 26 cases. For each case, it is either a case where the point is on the edge (returns on), where a ray from the point (x, y) to infinity along the line y = y cut through the edge (k += 1), or the ray does not pass through the edge (do nothing and continue). If the ray passes through an odd number of edges, it is within the curve, else outside of of the curve if it didn't return 'on'. See paper for more information on cases denoted in comments.
julia
function _point_filled_curve_orientation(
+ point, curve;
+ in::T = point_in, on::T = point_on, out::T = point_out, exact,
+) where {T}
+ x, y = GI.x(point), GI.y(point)
+ n = GI.npoint(curve)
+ n -= equals(GI.getpoint(curve, 1), GI.getpoint(curve, n)) ? 1 : 0
+ k = 0 # counter for ray crossings
+ p_start = GI.getpoint(curve, n)
+ for (i, p_end) in enumerate(GI.getpoint(curve))
+ i > n && break
+ v1 = GI.y(p_start) - y
+ v2 = GI.y(p_end) - y
+ if !((v1 < 0 && v2 < 0) || (v1 > 0 && v2 > 0)) # if not cases 11 or 26
+ u1, u2 = GI.x(p_start) - x, GI.x(p_end) - x
+ f = Predicates.cross((u1, u2), (v1, v2); exact)
+ if v2 > 0 && v1 ≤ 0 # Case 3, 9, 16, 21, 13, or 24
+ f == 0 && return on # Case 16 or 21
+ f > 0 && (k += 1) # Case 3 or 9
+ elseif v1 > 0 && v2 ≤ 0 # Case 4, 10, 19, 20, 12, or 25
+ f == 0 && return on # Case 19 or 20
+ f < 0 && (k += 1) # Case 4 or 10
+ elseif v2 == 0 && v1 < 0 # Case 7, 14, or 17
+ f == 0 && return on # Case 17
+ elseif v1 == 0 && v2 < 0 # Case 8, 15, or 18
+ f == 0 && return on # Case 18
+ elseif v1 == 0 && v2 == 0 # Case 1, 2, 5, 6, 22, or 23
+ u2 ≤ 0 && u1 ≥ 0 && return on # Case 1
+ u1 ≤ 0 && u2 ≥ 0 && return on # Case 2
+ end
+ end
+ p_start = p_end
+ end
+ return iseven(k) ? out : in
+end
Determines the types of interactions of a line with a filled-in curve. By filled-in curve, I am referring to the exterior ring of a poylgon, for example.
Returns a tuple of booleans: (in_curve, on_curve, out_curve).
If in_curve is true, some of the lines interior points interact with the curve's interior points. If on_curve is true, endpoints of either the line intersect with the curve or the line interacts with the polygon boundary. If out_curve is true, at least one segments of the line is outside the curve.
If closed_line is true, line is treated as a closed line where the first and last point are connected by a segment.
If line and curve meet, then at least one point is on boundary
julia
on_curve = true
+ if seg_val == line_cross
When crossing boundary, line is both in and out of curve
julia
in_curve = true
+ out_curve = true
+ else
+ if seg_val == line_over
+ sp = _point_segment_orientation(l_start, c_start, c_end)
+ lp = _point_segment_orientation(l_end, c_start, c_end)
+ if sp != point_in || lp != point_in
+ #=
+ Line crosses over segment endpoint, creating a hinge
+ with another segment.
+ =#
+ seg_val = line_hinge
+ end
+ end
+ if seg_val == line_hinge
+ #=
+ Can't determine all types of interactions (in, out) with
+ hinge as it could pass through multiple other segments
+ so calculate if segment endpoints and intersections are
+ in/out of filled curve
+ =#
+ ipoints = intersection_points(GI.Line(StaticArrays.SVector(l_start, l_end)), curve)
+ npoints = length(ipoints) # since hinge, at least one
+ dist_from_lstart = let l_start = l_start
+ x -> _euclid_distance(Float64, x, l_start)
+ end
+ sort!(ipoints, by = dist_from_lstart)
+ p_start = _tuple_point(l_start)
+ for i in 1:(npoints + 1)
+ p_end = i ≤ npoints ? _tuple_point(ipoints[i]) : l_end
+ mid_val = _point_filled_curve_orientation((p_start .+ p_end) ./ 2, curve; exact)
+ if mid_val == point_in
+ in_curve = true
+ elseif mid_val == point_out
+ out_curve = true
+ end
+ end
already checked segment against whole filled curve
julia
l_start = l_end
+ break
+ end
+ end
+ end
+ c_start = c_end
+ end
+ l_start = l_end
+ end
+ return in_curve, on_curve, out_curve
+end
Determines the types of interactions of a line with a polygon.
Returns a tuple of booleans: (in_poly, on_poly, out_poly).
If in_poly is true, some of the lines interior points interact with the polygon interior points. If in_poly is true, endpoints of either the line intersect with the polygon or the line interacts with the polygon boundary, including hole bounaries. If out_curve is true, at least one segments of the line is outside the polygon, including inside of holes.
If closed_line is true, line is treated as a closed line where the first and last point are connected by a segment.
`,142),t=[l];function p(k,e,r,E,d,g){return a(),i("div",null,t)}const c=s(h,[["render",p]]);export{o as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_geom_geom_processors.md.CXTtFMWr.lean.js b/previews/PR149/assets/source_methods_geom_relations_geom_geom_processors.md.CXTtFMWr.lean.js
new file mode 100644
index 000000000..7032e984e
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_geom_geom_processors.md.CXTtFMWr.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Line-curve interaction","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/geom_geom_processors.md","filePath":"source/methods/geom_relations/geom_geom_processors.md","lastUpdated":null}'),h={name:"source/methods/geom_relations/geom_geom_processors.md"},l=n("",142),t=[l];function p(k,e,r,E,d,g){return a(),i("div",null,t)}const c=s(h,[["render",p]]);export{o as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_intersects.md._s7iyRTF.js b/previews/PR149/assets/source_methods_geom_relations_intersects.md._s7iyRTF.js
new file mode 100644
index 000000000..a57f6ec3c
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_intersects.md._s7iyRTF.js
@@ -0,0 +1,27 @@
+import{_ as s,c as i,o as a,a6 as e}from"./chunks/framework.CDOaXZPW.js";const n="/GeometryOps.jl/previews/PR149/assets/ktaliog.DeeQUply.png",y=JSON.parse('{"title":"Intersection checks","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/intersects.md","filePath":"source/methods/geom_relations/intersects.md","lastUpdated":null}'),t={name:"source/methods/geom_relations/intersects.md"},p=e(`
The intersects function checks if a given geometry intersects with another geometry, or in other words, the either the interiors or boundaries of the two geometries intersect.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+line1 = GI.Line([(124.584961,-12.768946), (126.738281,-17.224758)])
+line2 = GI.Line([(123.354492,-15.961329), (127.22168,-14.008696)])
+f, a, p = lines(GI.getpoint(line1))
+lines!(GI.getpoint(line2))
+f
We can see that they intersect, so we expect intersects to return true, and we can visualize the intersection point in red.
This is the GeoInterface-compatible implementation.
Given that intersects is the exact opposite of disjoint, we simply pass the two inputs variables, swapped in order, to disjoint.
julia
"""
+ intersects(geom1, geom2)::Bool
+
+Return true if the interiors or boundaries of the two geometries interact.
+
+\`intersects\` returns the exact opposite result of \`disjoint\`.
+
+# Example
+
+\`\`\`jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+line1 = GI.Line([(124.584961,-12.768946), (126.738281,-17.224758)])
+line2 = GI.Line([(123.354492,-15.961329), (127.22168,-14.008696)])
+GO.intersects(line1, line2)
`,18),l=[p];function h(k,r,o,d,c,g){return a(),i("div",null,l)}const F=s(t,[["render",h]]);export{y as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_intersects.md._s7iyRTF.lean.js b/previews/PR149/assets/source_methods_geom_relations_intersects.md._s7iyRTF.lean.js
new file mode 100644
index 000000000..a80d9ef54
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_intersects.md._s7iyRTF.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as e}from"./chunks/framework.CDOaXZPW.js";const n="/GeometryOps.jl/previews/PR149/assets/ktaliog.DeeQUply.png",y=JSON.parse('{"title":"Intersection checks","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/intersects.md","filePath":"source/methods/geom_relations/intersects.md","lastUpdated":null}'),t={name:"source/methods/geom_relations/intersects.md"},p=e("",18),l=[p];function h(k,r,o,d,c,g){return a(),i("div",null,l)}const F=s(t,[["render",h]]);export{y as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_overlaps.md.Beu6L0zo.js b/previews/PR149/assets/source_methods_geom_relations_overlaps.md.Beu6L0zo.js
new file mode 100644
index 000000000..09a59a086
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_overlaps.md.Beu6L0zo.js
@@ -0,0 +1,212 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const l="/GeometryOps.jl/previews/PR149/assets/bbznugt.CgiryX2p.png",y=JSON.parse('{"title":"Overlaps","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/overlaps.md","filePath":"source/methods/geom_relations/overlaps.md","lastUpdated":null}'),p={name:"source/methods/geom_relations/overlaps.md"},t=n(`
The overlaps function checks if two geometries overlap. Two geometries can only overlap if they have the same dimension, and if they overlap, but one is not contained, within, or equal to the other.
Note that this means it is impossible for a single point to overlap with a single point and a line only overlaps with another line if only a section of each line is colinear.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.LineString([(0.0, 0.0), (0.0, 10.0)])
+l2 = GI.LineString([(0.0, -10.0), (0.0, 3.0)])
+f, a, p = lines(GI.getpoint(l1), color = :blue)
+scatter!(GI.getpoint(l1), color = :blue)
+lines!(GI.getpoint(l2), color = :orange)
+scatter!(GI.getpoint(l2), color = :orange)
+f
We can see that the two lines overlap in the plot:
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Note that that since only elements of the same dimension can overlap, any two geometries with traits that are of different dimensions autmoatically can return false.
For geometries with the same trait dimension, we must make sure that they share a point, an edge, or area for points, lines, and polygons/multipolygons respectivly, without being contained.
julia
"""
+ overlaps(geom1, geom2)::Bool
+
+Compare two Geometries of the same dimension and return true if their
+intersection set results in a geometry different from both but of the same
+dimension. This means one geometry cannot be within or contain the other and
+they cannot be equal
+
+# Examples
+\`\`\`jldoctest
+import GeometryOps as GO, GeoInterface as GI
+poly1 = GI.Polygon([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+poly2 = GI.Polygon([[(1,1), (1,6), (6,6), (6,1), (1,1)]])
+
+GO.overlaps(poly1, poly2)
output
julia
true
+\`\`\`
+"""
+overlaps(geom1, geom2)::Bool = overlaps(
+ GI.trait(geom1),
+ geom1,
+ GI.trait(geom2),
+ geom2,
+)
+
+"""
+ overlaps(::GI.AbstractTrait, geom1, ::GI.AbstractTrait, geom2)::Bool
+
+For any non-specified pair, all have non-matching dimensions, return false.
+"""
+overlaps(::GI.AbstractTrait, geom1, ::GI.AbstractTrait, geom2) = false
+
+"""
+ overlaps(
+ ::GI.MultiPointTrait, points1,
+ ::GI.MultiPointTrait, points2,
+ )::Bool
+
+If the multipoints overlap, meaning some, but not all, of the points within the
+multipoints are shared, return true.
+"""
+function overlaps(
+ ::GI.MultiPointTrait, points1,
+ ::GI.MultiPointTrait, points2,
+)
+ one_diff = false # assume that all the points are the same
+ one_same = false # assume that all points are different
+ for p1 in GI.getpoint(points1)
+ match_point = false
+ for p2 in GI.getpoint(points2)
+ if equals(p1, p2) # Point is shared
+ one_same = true
+ match_point = true
+ break
+ end
+ end
+ one_diff |= !match_point # Point isn't shared
+ one_same && one_diff && return true
+ end
+ return false
+end
+
+"""
+ overlaps(::GI.LineTrait, line1, ::GI.LineTrait, line)::Bool
+
+If the lines overlap, meaning that they are colinear but each have one endpoint
+outside of the other line, return true. Else false.
+"""
+overlaps(::GI.LineTrait, line1, ::GI.LineTrait, line) =
+ _overlaps((a1, a2), (b1, b2))
+
+"""
+ overlaps(
+ ::Union{GI.LineStringTrait, GI.LinearRing}, line1,
+ ::Union{GI.LineStringTrait, GI.LinearRing}, line2,
+ )::Bool
+
+If the curves overlap, meaning that at least one edge of each curve overlaps,
+return true. Else false.
+"""
+function overlaps(
+ ::Union{GI.LineStringTrait, GI.LinearRing}, line1,
+ ::Union{GI.LineStringTrait, GI.LinearRing}, line2,
+)
+ edges_a, edges_b = map(sort! ∘ to_edges, (line1, line2))
+ for edge_a in edges_a
+ for edge_b in edges_b
+ _overlaps(edge_a, edge_b) && return true
+ end
+ end
+ return false
+end
+
+"""
+ overlaps(
+ trait_a::GI.PolygonTrait, poly_a,
+ trait_b::GI.PolygonTrait, poly_b,
+ )::Bool
+
+If the two polygons intersect with one another, but are not equal, return true.
+Else false.
+"""
+function overlaps(
+ trait_a::GI.PolygonTrait, poly_a,
+ trait_b::GI.PolygonTrait, poly_b,
+)
+ edges_a, edges_b = map(sort! ∘ to_edges, (poly_a, poly_b))
+ return _line_intersects(edges_a, edges_b) &&
+ !equals(trait_a, poly_a, trait_b, poly_b)
+end
+
+"""
+ overlaps(
+ ::GI.PolygonTrait, poly1,
+ ::GI.MultiPolygonTrait, polys2,
+ )::Bool
+
+Return true if polygon overlaps with at least one of the polygons within the
+multipolygon. Else false.
+"""
+function overlaps(
+ ::GI.PolygonTrait, poly1,
+ ::GI.MultiPolygonTrait, polys2,
+)
+ for poly2 in GI.getgeom(polys2)
+ overlaps(poly1, poly2) && return true
+ end
+ return false
+end
+
+"""
+ overlaps(
+ ::GI.MultiPolygonTrait, polys1,
+ ::GI.PolygonTrait, poly2,
+ )::Bool
+
+Return true if polygon overlaps with at least one of the polygons within the
+multipolygon. Else false.
+"""
+overlaps(trait1::GI.MultiPolygonTrait, polys1, trait2::GI.PolygonTrait, poly2) =
+ overlaps(trait2, poly2, trait1, polys1)
+
+"""
+ overlaps(
+ ::GI.MultiPolygonTrait, polys1,
+ ::GI.MultiPolygonTrait, polys2,
+ )::Bool
+
+Return true if at least one pair of polygons from multipolygons overlap. Else
+false.
+"""
+function overlaps(
+ ::GI.MultiPolygonTrait, polys1,
+ ::GI.MultiPolygonTrait, polys2,
+)
+ for poly1 in GI.getgeom(polys1)
+ overlaps(poly1, polys2) && return true
+ end
+ return false
+end
+
+#= If the edges overlap, meaning that they are colinear but each have one endpoint
+outside of the other edge, return true. Else false. =#
+function _overlaps(
+ (a1, a2)::Edge,
+ (b1, b2)::Edge,
+ exact = _False(),
+)
cross = (x - x1) * Δyl - (y - y1) * Δxl
+ if cross == 0 # point is on line extending to infinity
is line between endpoints
julia
if abs(Δxl) >= abs(Δyl) # is line between endpoints
+ return Δxl > 0 ? x1 <= x <= x2 : x2 <= x <= x1
+ else
+ return Δyl > 0 ? y1 <= y <= y2 : y2 <= y <= y1
+ end
+ end
+ return false
+end
+
+#= Returns true if there is at least one intersection between edges within the
+two lists of edges. =#
+function _line_intersects(
+ edges_a::Vector{<:Edge},
+ edges_b::Vector{<:Edge};
+)
`,37),e=[t];function h(k,r,d,g,F,o){return a(),i("div",null,e)}const c=s(p,[["render",h]]);export{y as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_overlaps.md.Beu6L0zo.lean.js b/previews/PR149/assets/source_methods_geom_relations_overlaps.md.Beu6L0zo.lean.js
new file mode 100644
index 000000000..07385ab33
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_overlaps.md.Beu6L0zo.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const l="/GeometryOps.jl/previews/PR149/assets/bbznugt.CgiryX2p.png",y=JSON.parse('{"title":"Overlaps","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/overlaps.md","filePath":"source/methods/geom_relations/overlaps.md","lastUpdated":null}'),p={name:"source/methods/geom_relations/overlaps.md"},t=n("",37),e=[t];function h(k,r,d,g,F,o){return a(),i("div",null,e)}const c=s(p,[["render",h]]);export{y as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_touches.md.BaNQMEDg.js b/previews/PR149/assets/source_methods_geom_relations_touches.md.BaNQMEDg.js
new file mode 100644
index 000000000..0415a0191
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_touches.md.BaNQMEDg.js
@@ -0,0 +1,174 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const t="/GeometryOps.jl/previews/PR149/assets/hxpbxsu.BEFUMtlf.png",c=JSON.parse('{"title":"Touches","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/touches.md","filePath":"source/methods/geom_relations/touches.md","lastUpdated":null}'),h={name:"source/methods/geom_relations/touches.md"},l=n(`
The touches function checks if one geometry touches another geometry. In other words, the interiors of the two geometries don't interact, but one of the geometries must have a boundary point that interacts with either the other geometies interior or boundary.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.Line([(0.0, 0.0), (1.0, 0.0)])
+l2 = GI.Line([(1.0, 0.0), (1.0, -1.0)])
+
+f, a, p = lines(GI.getpoint(l1))
+lines!(GI.getpoint(l2))
+f
We can see that these two lines touch only at their endpoints.
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait.
Each of these calls a method in the geom_geom_processors file. The methods in this file determine if the given geometries meet a set of criteria. For the touches function and arguments g1 and g2, this criteria is as follows: - points of g1 are not allowed to be in the interior of g2 - points of g1 are allowed to be on the boundary of g2 - points of g1 are allowed to be in the exterior of g2 - no points of g1 are required to be in the interior of g2 - at least one point of g1 is required to be on the boundary of g2 - no points of g1 are required to be in the exterior of g2
The code for the specific implementations is in the geom_geom_processors file.
julia
const TOUCHES_POINT_ALLOWED = (in_allow = false, on_allow = true, out_allow = false)
+const TOUCHES_CURVE_ALLOWED = (over_allow = false, cross_allow = false, on_allow = true, out_allow = true)
+const TOUCHES_POLYGON_ALLOWS = (in_allow = false, on_allow = true, out_allow = true)
+const TOUCHES_REQUIRES = (in_require = false, on_require = true, out_require = false)
+const TOUCHES_EXACT = (exact = _False(),)
+
+"""
+ touches(geom1, geom2)::Bool
+
+Return \`true\` if the first geometry touches the second geometry. In other words,
+the two interiors cannot interact, but one of the geometries must have a
+boundary point that interacts with either the other geometies interior or
+boundary.
+
+# Examples
+\`\`\`jldoctest setup=:(using GeometryOps, GeometryBasics)
+import GeometryOps as GO, GeoInterface as GI
+
+l1 = GI.Line([(0.0, 0.0), (1.0, 0.0)])
+l2 = GI.Line([(1.0, 1.0), (1.0, -1.0)])
+
+GO.touches(l1, l2)
#= Linestring touches another line if at least one bounday point interacts with
+the bounday of interior of the other line, but the interiors don't interact. =#
+_touches(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ TOUCHES_CURVE_ALLOWED...,
+ TOUCHES_REQUIRES...,
+ TOUCHES_EXACT...,
+ closed_line = false,
+ closed_curve = false,
+)
+
+
+#= Linestring touches a linearring if at least one of the boundary points of the
+line interacts with the linear ring, but their interiors can't interact. =#
+_touches(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ TOUCHES_CURVE_ALLOWED...,
+ TOUCHES_REQUIRES...,
+ TOUCHES_EXACT...,
+ closed_line = false,
+ closed_curve = true,
+)
+
+#= Linestring touches a polygon if at least one of the boundary points of the
+line interacts with the boundary of the polygon. =#
+_touches(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ TOUCHES_POLYGON_ALLOWS...,
+ TOUCHES_REQUIRES...,
+ TOUCHES_EXACT...,
+ closed_line = false,
+)
#= Linearring touches a linestring if at least one of the boundary points of the
+line interacts with the linear ring, but their interiors can't interact. =#
+_touches(
+ trait1::GI.LinearRingTrait, g1,
+ trait2::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _touches(trait2, g2, trait1, g1)
+
+#= Linearring cannot touch another linear ring since they are both exclusively
+made up of interior points and no bounday points =#
+_touches(
+ ::GI.LinearRingTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = false
+
+#= Linearring touches a polygon if at least one of the points of the ring
+interact with the polygon bounday and non are in the polygon interior. =#
+_touches(
+ ::GI.LinearRingTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ TOUCHES_POLYGON_ALLOWS...,
+ TOUCHES_REQUIRES...,
+ TOUCHES_EXACT...,
+ closed_line = true,
+)
#= Polygon touches a curve if at least one of the curve bounday points interacts
+with the polygon's bounday and no curve points interact with the interior.=#
+_touches(
+ trait1::GI.PolygonTrait, g1,
+ trait2::GI.AbstractCurveTrait, g2
+) = _touches(trait2, g2, trait1, g1)
+
+
+#= Polygon touches another polygon if they share at least one boundary point and
+no interior points. =#
+_touches(
+ ::GI.PolygonTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _polygon_polygon_process(
+ g1, g2;
+ TOUCHES_POLYGON_ALLOWS...,
+ TOUCHES_REQUIRES...,
+ TOUCHES_EXACT...,
+)
#= Geometry touch a multi-geometry or a collection if the geometry touches at
+least one of the elements of the collection. =#
+function _touches(
+ ::Union{GI.PointTrait, GI.AbstractCurveTrait, GI.PolygonTrait}, g1,
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g2,
+)
+ for sub_g2 in GI.getgeom(g2)
+ !touches(g1, sub_g2) && return false
+ end
+ return true
+end
#= Multi-geometry or a geometry collection touches a geometry if at least one
+elements of the collection touches the geometry. =#
+function _touches(
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g1,
+ ::GI.AbstractGeometryTrait, g2,
+)
+ for sub_g1 in GI.getgeom(g1)
+ !touches(sub_g1, g2) && return false
+ end
+ return true
+end
`,41),e=[l];function p(k,r,E,g,d,o){return a(),i("div",null,e)}const F=s(h,[["render",p]]);export{c as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_touches.md.BaNQMEDg.lean.js b/previews/PR149/assets/source_methods_geom_relations_touches.md.BaNQMEDg.lean.js
new file mode 100644
index 000000000..d0d033feb
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_touches.md.BaNQMEDg.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const t="/GeometryOps.jl/previews/PR149/assets/hxpbxsu.BEFUMtlf.png",c=JSON.parse('{"title":"Touches","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/touches.md","filePath":"source/methods/geom_relations/touches.md","lastUpdated":null}'),h={name:"source/methods/geom_relations/touches.md"},l=n("",41),e=[l];function p(k,r,E,g,d,o){return a(),i("div",null,e)}const F=s(h,[["render",p]]);export{c as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_within.md.DSfnbsO1.js b/previews/PR149/assets/source_methods_geom_relations_within.md.DSfnbsO1.js
new file mode 100644
index 000000000..41a59d5c1
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_within.md.DSfnbsO1.js
@@ -0,0 +1,193 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/dvvvcck._0R9BbFk.png",c=JSON.parse('{"title":"Within","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/within.md","filePath":"source/methods/geom_relations/within.md","lastUpdated":null}'),t={name:"source/methods/geom_relations/within.md"},l=n(`
The within function checks if one geometry is inside another geometry. This requires that the two interiors intersect and that the interior and boundary of the first geometry is not in the exterior of the second geometry.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.LineString([(0.0, 0.0), (1.0, 0.0), (0.0, 0.1)])
+l2 = GI.LineString([(0.25, 0.0), (0.75, 0.0)])
+f, a, p = lines(GI.getpoint(l1), color = :blue)
+scatter!(GI.getpoint(l1), color = :blue)
+lines!(GI.getpoint(l2), color = :orange)
+scatter!(GI.getpoint(l2), color = :orange)
+f
We can see that all of the points and edges of l2 are within l1, so l2 is within l1, but l1 is not within l2
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait.
Each of these calls a method in the geom_geom_processors file. The methods in this file determine if the given geometries meet a set of criteria. For the within function and arguments g1 and g2, this criteria is as follows: - points of g1 are allowed to be in the interior of g2 (either through overlap or crossing for lines) - points of g1 are allowed to be on the boundary of g2 - points of g1 are not allowed to be in the exterior of g2 - at least one point of g1 is required to be in the interior of g2 - no points of g1 are required to be on the boundary of g2 - no points of g1 are required to be in the exterior of g2
The code for the specific implementations is in the geom_geom_processors file.
julia
const WITHIN_POINT_ALLOWS = (in_allow = true, on_allow = false, out_allow = false)
+const WITHIN_CURVE_ALLOWS = (over_allow = true, cross_allow = true, on_allow = true, out_allow = false)
+const WITHIN_POLYGON_ALLOWS = (in_allow = true, on_allow = true, out_allow = false)
+const WITHIN_REQUIRES = (in_require = true, on_require = false, out_require = false)
+const WITHIN_EXACT = (exact = _False(),)
+
+"""
+ within(geom1, geom2)::Bool
+
+Return \`true\` if the first geometry is completely within the second geometry.
+The interiors of both geometries must intersect and the interior and boundary of
+the primary geometry (geom1) must not intersect the exterior of the secondary
+geometry (geom2).
+
+Furthermore, \`within\` returns the exact opposite result of \`contains\`.
+
+# Examples
+\`\`\`jldoctest setup=:(using GeometryOps, GeometryBasics)
+import GeometryOps as GO, GeoInterface as GI
+
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = (1, 2)
+GO.within(point, line)
Point is within another point if those points are equal.
julia
_within(
+ ::GI.PointTrait, g1,
+ ::GI.PointTrait, g2,
+) = equals(g1, g2)
+
+#= Point is within a linestring if it is on a vertex or an edge of that line,
+excluding the start and end vertex if the line is not closed. =#
+_within(
+ ::GI.PointTrait, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _point_curve_process(
+ g1, g2;
+ WITHIN_POINT_ALLOWS...,
+ closed_curve = false,
+)
Point is within a linearring if it is on a vertex or an edge of that ring.
julia
_within(
+ ::GI.PointTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = _point_curve_process(
+ g1, g2;
+ WITHIN_POINT_ALLOWS...,
+ closed_curve = true,
+)
+
+#= Point is within a polygon if it is inside of that polygon, excluding edges,
+vertices, and holes. =#
+_within(
+ ::GI.PointTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _point_polygon_process(
+ g1, g2;
+ WITHIN_POINT_ALLOWS...,
+ WITHIN_EXACT...,
+)
No geometries other than points can be within points
#= Linestring is within another linestring if their interiors intersect and no
+points of the first line are in the exterior of the second line. =#
+_within(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ WITHIN_CURVE_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = false,
+ closed_curve = false,
+)
+
+#= Linestring is within a linear ring if their interiors intersect and no points
+of the line are in the exterior of the ring. =#
+_within(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ WITHIN_CURVE_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = false,
+ closed_curve = true,
+)
+
+#= Linestring is within a polygon if their interiors intersect and no points of
+the line are in the exterior of the polygon, although they can be on an edge. =#
+_within(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ WITHIN_POLYGON_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = false,
+)
#= Linearring is within a linestring if their interiors intersect and no points
+of the ring are in the exterior of the line. =#
+_within(
+ ::GI.LinearRingTrait, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ WITHIN_CURVE_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = true,
+ closed_curve = false,
+)
+
+#= Linearring is within another linearring if their interiors intersect and no
+points of the first ring are in the exterior of the second ring. =#
+_within(
+ ::GI.LinearRingTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ WITHIN_CURVE_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = true,
+ closed_curve = true,
+)
+
+#= Linearring is within a polygon if their interiors intersect and no points of
+the ring are in the exterior of the polygon, although they can be on an edge. =#
+_within(
+ ::GI.LinearRingTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ WITHIN_POLYGON_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = true,
+)
#= Polygon is within another polygon if the interior of the first polygon
+intersects with the interior of the second and no points of the first polygon
+are outside of the second polygon. =#
+_within(
+ ::GI.PolygonTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _polygon_polygon_process(
+ g1, g2;
+ WITHIN_POLYGON_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+)
Geometries within multi-geometry/geometry collections
julia
#= Geometry is within a multi-geometry or a collection if the geometry is within
+at least one of the collection elements. =#
+function _within(
+ ::Union{GI.PointTrait, GI.AbstractCurveTrait, GI.PolygonTrait}, g1,
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g2,
+)
+ for sub_g2 in GI.getgeom(g2)
+ within(g1, sub_g2) && return true
+ end
+ return false
+end
Multi-geometry/geometry collections within geometries
julia
#= Multi-geometry or a geometry collection is within a geometry if all
+elements of the collection are within the geometry. =#
+function _within(
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g1,
+ ::GI.AbstractGeometryTrait, g2,
+)
+ for sub_g1 in GI.getgeom(g1)
+ !within(sub_g1, g2) && return false
+ end
+ return true
+end
`,41),p=[l];function e(k,r,E,g,d,y){return a(),i("div",null,p)}const F=s(t,[["render",e]]);export{c as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_geom_relations_within.md.DSfnbsO1.lean.js b/previews/PR149/assets/source_methods_geom_relations_within.md.DSfnbsO1.lean.js
new file mode 100644
index 000000000..9cc0c4bdf
--- /dev/null
+++ b/previews/PR149/assets/source_methods_geom_relations_within.md.DSfnbsO1.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/dvvvcck._0R9BbFk.png",c=JSON.parse('{"title":"Within","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/within.md","filePath":"source/methods/geom_relations/within.md","lastUpdated":null}'),t={name:"source/methods/geom_relations/within.md"},l=n("",41),p=[l];function e(k,r,E,g,d,y){return a(),i("div",null,p)}const F=s(t,[["render",e]]);export{c as __pageData,F as default};
diff --git a/previews/PR149/assets/source_methods_orientation.md.DjSAwkX1.js b/previews/PR149/assets/source_methods_orientation.md.DjSAwkX1.js
new file mode 100644
index 000000000..bd7a973ad
--- /dev/null
+++ b/previews/PR149/assets/source_methods_orientation.md.DjSAwkX1.js
@@ -0,0 +1,97 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Orientation","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/orientation.md","filePath":"source/methods/orientation.md","lastUpdated":null}'),p={name:"source/methods/orientation.md"},l=n(`
A polygon is concave if it has at least one interior angle greater than 180 degrees, meaning that the interior of the polygon is not a convex set.
These are all adapted from Turf.jl.
The may not necessarily be what want in the end but work for now!
julia
"""
+ isclockwise(line::Union{LineString, Vector{Position}})::Bool
+
+Take a ring and return true or false whether or not the ring is clockwise or
+counter-clockwise.
+
+# Example
+
+\`\`\`jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+ring = GI.LinearRing([(0, 0), (1, 1), (1, 0), (0, 0)])
+GO.isclockwise(ring)
output
julia
true
+\`\`\`
+"""
+isclockwise(geom)::Bool = isclockwise(GI.trait(geom), geom)
+
+function isclockwise(::AbstractCurveTrait, line)::Bool
+ sum = 0.0
+ prev = GI.getpoint(line, 1)
+ for p in GI.getpoint(line)
sum will be zero for the first point as x is subtracted from itself
julia
sum += (GI.x(p) - GI.x(prev)) * (GI.y(p) + GI.y(prev))
+ prev = p
+ end
+
+ return sum > 0.0
+end
+
+"""
+ isconcave(poly::Polygon)::Bool
+
+Take a polygon and return true or false as to whether it is concave or not.
+
+# Examples
+\`\`\`jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+poly = GI.Polygon([[(0, 0), (0, 1), (1, 1), (1, 0), (0, 0)]])
+GO.isconcave(poly)
GI.npoint(exterior) <= 4 && return false
+ n = GI.npoint(exterior) - 1
+
+ for i in 1:n
+ j = ((i + 1) % n) === 0 ? 1 : (i + 1) % n
+ m = ((i + 2) % n) === 0 ? 1 : (i + 2) % n
+
+ pti = GI.getpoint(exterior, i)
+ ptj = GI.getpoint(exterior, j)
+ ptm = GI.getpoint(exterior, m)
+
+ dx1 = GI.x(ptm) - GI.x(ptj)
+ dy1 = GI.y(ptm) - GI.y(ptj)
+ dx2 = GI.x(pti) - GI.x(ptj)
+ dy2 = GI.y(pti) - GI.y(ptj)
+
+ cross = (dx1 * dy2) - (dy1 * dx2)
+
+ if i === 0
+ sign = cross > 0
+ elseif sign !== (cross > 0)
+ return true
+ end
+ end
+
+ return false
+end
This is commented out.
julia
"""
+ isparallel(line1::LineString, line2::LineString)::Bool
+
+Return \`true\` if each segment of \`line1\` is parallel to the correspondent segment of \`line2\`
+
+## Examples
julia import GeoInterface as GI, GeometryOps as GO julia> line1 = GI.LineString([(9.170356, 45.477985), (9.164434, 45.482551), (9.166644, 45.484003)]) GeoInterface.Wrappers.LineString{false, false, Vector{Tuple{Float64, Float64}}, Nothing, Nothing}([(9.170356, 45.477985), (9.164434, 45.482551), (9.166644, 45.484003)], nothing, nothing)
`,28),t=[l];function h(e,k,r,d,E,g){return a(),i("div",null,t)}const c=s(p,[["render",h]]);export{y as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_orientation.md.DjSAwkX1.lean.js b/previews/PR149/assets/source_methods_orientation.md.DjSAwkX1.lean.js
new file mode 100644
index 000000000..b79d40178
--- /dev/null
+++ b/previews/PR149/assets/source_methods_orientation.md.DjSAwkX1.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Orientation","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/orientation.md","filePath":"source/methods/orientation.md","lastUpdated":null}'),p={name:"source/methods/orientation.md"},l=n("",28),t=[l];function h(e,k,r,d,E,g){return a(),i("div",null,t)}const c=s(p,[["render",h]]);export{y as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_polygonize.md.B9XUV_w-.js b/previews/PR149/assets/source_methods_polygonize.md.B9XUV_w-.js
new file mode 100644
index 000000000..e69ed9880
--- /dev/null
+++ b/previews/PR149/assets/source_methods_polygonize.md.B9XUV_w-.js
@@ -0,0 +1,289 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Polygonizing raster data","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/polygonize.md","filePath":"source/methods/polygonize.md","lastUpdated":null}'),h={name:"source/methods/polygonize.md"},l=n(`
export polygonize
+
+#=
+The methods in this file convert a raster image into a set of polygons,
+by contour detection using a clockwise Moore neighborhood method.
+
+The resulting polygons are snapped to the boundaries of the cells of the input raster,
+so they will look different from traditional contours from a plotting package.
+
+The main entry point is the \`polygonize\` function.
+
+\`\`\`@docs
+polygonize
+\`\`\`
+
+# Example
+
+Here's a basic example, using the \`Makie.peaks()\` function. First, let's investigate the nature of the function:
+\`\`\`@example polygonize
+using Makie, GeometryOps
+n = 49
+xs, ys = LinRange(-3, 3, n), LinRange(-3, 3, n)
+zs = Makie.peaks(n)
+z_max_value = maximum(abs.(extrema(zs)))
+f, a, p = heatmap(
+ xs, ys, zs;
+ axis = (; aspect = DataAspect(), title = "Exact function")
+)
+cb = Colorbar(f[1, 2], p; label = "Z-value")
+f
+\`\`\`
+
+Now, we can use the \`polygonize\` function to convert the raster data into polygons.
+
+For this particular example, we chose a range of z-values between 0.8 and 3.2,
+which would provide two distinct polyogns with holes.
+
+\`\`\`@example polygonize
+polygons = polygonize(xs, ys, 0.8 .< zs .< 3.2)
+\`\`\`
+This returns a \`GI.MultiPolygon\`, which is directly plottable. Let's see how these look:
+
+\`\`\`@example polygonize
+f, a, p = poly(polygons; label = "Polygonized polygons", axis = (; aspect = DataAspect()))
+\`\`\`
+
+Finally, let's plot the Makie contour lines on top, to see how the polygonization compares:
+\`\`\`@example polygonize
+contour!(a, xs, ys, zs; labels = true, levels = [0.8, 3.2], label = "Contour lines")
+f
+\`\`\`
+
+# Implementation
+
+The implementation follows:
+=#
+
+"""
+ polygonize(A::AbstractMatrix{Bool}; kw...)
+ polygonize(f, A::AbstractMatrix; kw...)
+ polygonize(xs, ys, A::AbstractMatrix{Bool}; kw...)
+ polygonize(f, xs, ys, A::AbstractMatrix; kw...)
+
+Polygonize an \`AbstractMatrix\` of values, currently to a single class of polygons.
+
+Returns a \`MultiPolygon\` for \`Bool\` values and \`f\` return values, and
+a \`FeatureCollection\` of \`Feature\`s holding \`MultiPolygon\` for all other values.
+
+
+Function \`f\` should return either \`true\` or \`false\` or a transformation
+of values into simpler groups, especially useful for floating point arrays.
+
+If \`xs\` and \`ys\` are ranges, they are used as the pixel/cell center points.
+If they are \`Vector\` of \`Tuple\` they are used as the lower and upper bounds of each pixel/cell.
Keywords
julia
- \`minpoints\`: ignore polygons with less than \`minpoints\` points.
+- \`values\`: the values to turn into polygons. By default these are \`union(A)\`,
+ If function \`f\` is passed these refer to the return values of \`f\`, by
+ default \`union(map(f, A)\`. If values \`Bool\`, false is ignored and a single
+ \`MultiPolygon\` is returned rather than a \`FeatureCollection\`.
When there are two possible node, choose the node that is the furthest to the left We also need to check if we are on a straight line to avoid adding unnecessary points.
julia
selectednode, remainingnode, straightline = if currentnode[1] == nextnode[1] # vertical
+ wasincreasing = nextnode[2] > currentnode[2]
+ firstisstraight = nextnode[1] == c1[1]
+ firstisleft = nextnode[1] > c1[1]
+ secondisstraight = nextnode[1] == c2[1]
+ secondisleft = nextnode[1] > c2[1]
+ if firstisstraight
+ if secondisleft
+ if wasincreasing
+ (c2, c1, turning)
+ else
+ (c1, c2, straight)
+ end
+ else
+ if wasincreasing
+ (c1, c2, straight)
+ else
+ (c2, c1, secondisstraight)
+ end
+ end
+ elseif firstisleft
+ if wasincreasing
+ (c1, c2, turning)
+ else
+ (c2, c1, secondisstraight)
+ end
+ else # firstisright
+ if wasincreasing
+ (c2, c1, secondisstraight)
+ else
+ (c1, c2, turning)
+ end
+ end
+ else # horizontal
+ wasincreasing = nextnode[1] > currentnode[1]
+ firstisstraight = nextnode[2] == c1[2]
+ firstisleft = nextnode[2] > c1[2]
+ secondisleft = nextnode[2] > c2[2]
+ secondisstraight = nextnode[2] == c2[2]
+ if firstisstraight
+ if secondisleft
+ if wasincreasing
+ (c1, c2, straight)
+ else
+ (c2, c1, turning)
+ end
+ else
+ if wasincreasing
+ (c2, c1, turning)
+ else
+ (c1, c2, straight)
+ end
+ end
+ elseif firstisleft
+ if wasincreasing
+ (c2, c1, secondisstraight)
+ else
+ (c1, c2, turning)
+ end
+ else # firstisright
+ if wasincreasing
+ (c1, c2, turning)
+ else
+ (c2, c1, secondisstraight)
+ end
+ end
+ end
Update the current and next nodes with the next and selected nodes
julia
currentnode, nextnode = nextnode, selectednode
Update the current node or add a new node to the ring
julia
if straightline
replace the last node we don't need it
julia
ring[end] = nextnode
+ else
add a new node, we have turned a corner
julia
push!(ring, nextnode)
+ end
If the ring is closed, break the loop and start a new one
julia
nextnode == firstnode && break
+ end
+ end
Define wrapped LinearRings, with embedded extents so we only calculate them once
julia
linearrings = map(rings) do ring
+ extent = GI.extent(GI.LinearRing(ring))
+ GI.LinearRing(ring; extent, crs)
+ end
Separate exteriors from holes by winding direction
julia
direction = (last(last(xs)) - first(first(xs))) * (last(last(ys)) - first(first(ys)))
+ exterior_inds = if direction > 0
+ .!isclockwise.(linearrings)
+ else
+ isclockwise.(linearrings)
+ end
+ holes = linearrings[.!exterior_inds]
+ polygons = map(view(linearrings, exterior_inds)) do lr
+ GI.Polygon([lr]; extent=GI.extent(lr), crs)
+ end
Then we add the holes to the polygons they are inside of
julia
assigned = fill(false, length(holes))
+ for i in eachindex(holes)
+ hole = holes[i]
+ prepared_hole = GI.LinearRing(holes[i]; extent=GI.extent(holes[i]))
+ for poly in polygons
+ exterior = GI.Polygon(StaticArrays.SVector(GI.getexterior(poly)); extent=GI.extent(poly))
+ if covers(exterior, prepared_hole)
Hole is in the exterior, so add it to the polygon
julia
push!(poly.geom, hole)
+ assigned[i] = true
+ break
+ end
+ end
+ end
+
+ assigned_holes = count(assigned)
+ assigned_holes == length(holes) || @warn "Not all holes were assigned to polygons, $(length(holes) - assigned_holes) where missed from $(length(holes)) holes and $(length(polygons)) polygons"
+
+ if isempty(polygons)
TODO: this really should return an emtpty MultiPolygon but GeoInterface wrappers cant do that yet, which is not ideal...
julia
@warn "No polgons found, check your data or try another function for \`f\`"
+ return nothing
+ else
If we actually fetched an existing node, update it
julia
if existingnodes[1] != node
+ dict[key] = (existingnodes[1], node)
+ end
+end
+
+function _pixel_edges(f, xs::AbstractVector{T}, ys::AbstractVector{T}, A) where T<:Tuple
+ edges = Dict{T,Tuple{T,T}}()
First we collect all the edges around target pixels
julia
fi, fj = map(first, axes(A))
+ li, lj = map(last, axes(A))
+ for j in axes(A, 2)
+ y1, y2 = ys[j]
+ for i in axes(A, 1)
+ if f(A[i, j]) # This is a pixel inside a polygon
xs and ys hold pixel bounds
julia
x1, x2 = xs[i]
We check the Von Neumann neighborhood to decide what edges are needed, if any.
julia
(j == fi || !f(A[i, j-1])) && update_edge!(edges, (x1, y1), (x2, y1)) # S
+ (i == fj || !f(A[i-1, j])) && update_edge!(edges, (x1, y2), (x1, y1)) # W
+ (j == lj || !f(A[i, j+1])) && update_edge!(edges, (x2, y2), (x1, y2)) # N
+ (i == li || !f(A[i+1, j])) && update_edge!(edges, (x2, y1), (x2, y2)) # E
+ end
+ end
+ end
+ return edges
+end
`,86),p=[l];function t(k,e,d,E,r,g){return a(),i("div",null,p)}const c=s(h,[["render",t]]);export{o as __pageData,c as default};
diff --git a/previews/PR149/assets/source_methods_polygonize.md.B9XUV_w-.lean.js b/previews/PR149/assets/source_methods_polygonize.md.B9XUV_w-.lean.js
new file mode 100644
index 000000000..6fe2b9b69
--- /dev/null
+++ b/previews/PR149/assets/source_methods_polygonize.md.B9XUV_w-.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Polygonizing raster data","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/polygonize.md","filePath":"source/methods/polygonize.md","lastUpdated":null}'),h={name:"source/methods/polygonize.md"},l=n("",86),p=[l];function t(k,e,d,E,r,g){return a(),i("div",null,p)}const c=s(h,[["render",t]]);export{o as __pageData,c as default};
diff --git a/previews/PR149/assets/source_primitives.md.YB3uDiz_.js b/previews/PR149/assets/source_primitives.md.YB3uDiz_.js
new file mode 100644
index 000000000..96e353aed
--- /dev/null
+++ b/previews/PR149/assets/source_primitives.md.YB3uDiz_.js
@@ -0,0 +1,335 @@
+import{_ as s,c as i,o as a,a6 as t}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Primitive functions","description":"","frontmatter":{},"headers":[],"relativePath":"source/primitives.md","filePath":"source/primitives.md","lastUpdated":null}'),n={name:"source/primitives.md"},h=t(`
This file mainly defines the apply and applyreduce functions, and some related functionality.
In general, the idea behind the apply framework is to take as input any geometry, vector of geometries, or feature collection, deconstruct it to the given trait target (any arbitrary GI.AbstractTrait or TraitTarget union thereof, like PointTrait or PolygonTrait) and perform some operation on it.
This allows for a simple and consistent framework within which users can define their own operations trivially easily, and removes a lot of the complexity involved with handling complex geometry structures.
For example, a simple way to flip the x and y coordinates of a geometry is:
julia
flipped_geom = GO.apply(GI.PointTrait(), geom) do p
+ (GI.y(p), GI.x(p))
+end
As simple as that. There's no need to implement your own decomposition because it's done for you.
Functions like flip, reproject, transform, even segmentize and simplify have been implemented using the apply framework. Similarly, centroid, area and distance have been implemented using the applyreduce framework.
Lazily flatten any AbstractArray, iterator, FeatureCollectionTrait, FeatureTrait or AbstractGeometryTrait object obj, so that objects with the target trait are returned by the iterator.
If f is passed in it will be applied to the target geometries.
By default geometries will be rebuilt as a GeoInterface.Wrappers geometry, but rebuild can have methods added to it to dispatch on geometries from other packages and specify how to rebuild them.
We pass threading and calc_extent as types, not simple boolean values.
This is to help compilation - with a type to hold on to, it's easier for the compiler to separate threaded and non-threaded code paths.
Note that if we didn't include the parent abstract type, this would have been really type unstable, since the compiler couldn't tell what would be returned!
We had to add the type annotation on the _booltype(::Bool) method for this reason as well.
julia
abstract type BoolsAsTypes end
+struct _True <: BoolsAsTypes end
+struct _False <: BoolsAsTypes end
+
+@inline _booltype(x::Bool)::BoolsAsTypes = x ? _True() : _False()
+@inline _booltype(x::BoolsAsTypes)::BoolsAsTypes = x
+
+"""
+ TraitTarget{T}
+
+This struct holds a trait parameter or a union of trait parameters.
+
+It is primarily used for dispatch into methods which select trait levels,
+like \`apply\`, or as a parameter to \`target\`.
+
+# Constructors
+\`\`\`julia
+TraitTarget(GI.PointTrait())
+TraitTarget(GI.LineStringTrait(), GI.LinearRingTrait()) # and other traits as you may like
+TraitTarget(TraitTarget(...))
There are also type based constructors available, but that's not advised.
\`\`\`
+
+"""
+struct TraitTarget{T} end
+TraitTarget(::Type{T}) where T = TraitTarget{T}()
+TraitTarget(::T) where T<:GI.AbstractTrait = TraitTarget{T}()
+TraitTarget(::TraitTarget{T}) where T = TraitTarget{T}()
+TraitTarget(::Type{<:TraitTarget{T}}) where T = TraitTarget{T}()
+TraitTarget(traits::GI.AbstractTrait...) = TraitTarget{Union{map(typeof, traits)...}}()
+
+const THREADED_KEYWORD = "- \`threaded\`: \`true\` or \`false\`. Whether to use multithreading. Defaults to \`false\`."
+const CRS_KEYWORD = "- \`crs\`: The CRS to attach to geometries. Defaults to \`nothing\`."
+const CALC_EXTENT_KEYWORD = "- \`calc_extent\`: \`true\` or \`false\`. Whether to calculate the extent. Defaults to \`false\`."
+
+const APPLY_KEYWORDS = """
+$THREADED_KEYWORD
+$CRS_KEYWORD
+$CALC_EXTENT_KEYWORD
+"""
apply applies some function to every geometry matching the Target GeoInterface trait, in some arbitrarily nested object made up of:
AbstractArrays (we also try to iterate other non-GeoInteface compatible object)
FeatureCollectionTrait objects
FeatureTrait objects
AbstractGeometryTrait objects
apply recursively calls itself through these nested layers until it reaches objects with the Target GeoInterface trait. When found apply applies the function f, and stops.
The outer recursive functions then progressively rebuild the object using GeoInterface objects matching the original traits.
If PointTrait is found but it is not the Target, an error is thrown. This likely means the object contains a different geometry trait to the target, such as MultiPointTrait when LineStringTrait was specified.
To handle this possibility it may be necessary to make Target a Union of traits found at the same level of nesting, and define methods of f to handle all cases.
Be careful making a union across "levels" of nesting, e.g. Union{FeatureTrait,PolygonTrait}, as _apply will just never reach PolygonTrait when all the polygons are wrapped in a FeatureTrait object.
extent and crs can be embedded in all geometries, features, and feature collections as part of apply. Geometries deeper than Target will of course not have new extent or crs embedded.
calc_extent signals to recalculate an Extent and embed it.
Threading is used at the outermost level possible - over an array, feature collection, or e.g. a MultiPolygonTrait where each PolygonTrait sub-geometry may be calculated on a different thread.
Currently, threading defaults to false for all objects, but can be turned on by passing the keyword argument threaded=true to apply.
julia
"""
+ apply(f, target::Union{TraitTarget, GI.AbstractTrait}, obj; kw...)
+
+Reconstruct a geometry, feature, feature collection, or nested vectors of
+either using the function \`f\` on the \`target\` trait.
+
+\`f(target_geom) => x\` where \`x\` also has the \`target\` trait, or a trait that can
+be substituted. For example, swapping \`PolgonTrait\` to \`MultiPointTrait\` will fail
+if the outer object has \`MultiPolygonTrait\`, but should work if it has \`FeatureTrait\`.
+
+Objects "shallower" than the target trait are always completely rebuilt, like
+a \`Vector\` of \`FeatureCollectionTrait\` of \`FeatureTrait\` when the target
+has \`PolygonTrait\` and is held in the features. These will always be GeoInterface
+geometries/feature/feature collections. But "deeper" objects may remain
+unchanged or be whatever GeoInterface compatible objects \`f\` returns.
+
+The result is a functionally similar geometry with values depending on \`f\`.
+
+$APPLY_KEYWORDS
+
+# Example
+
+Flipped point the order in any feature or geometry, or iterables of either:
+
+\`\`\`julia
+import GeoInterface as GI
+import GeometryOps as GO
+geom = GI.Polygon([GI.LinearRing([(1, 2), (3, 4), (5, 6), (1, 2)]),
+ GI.LinearRing([(3, 4), (5, 6), (6, 7), (3, 4)])])
+
+flipped_geom = GO.apply(GI.PointTrait, geom) do p
+ (GI.y(p), GI.x(p))
+end
+\`\`\`
+"""
+@inline function apply(
+ f::F, target, geom; calc_extent=false, threaded=false, kw...
+) where F
+ threaded = _booltype(threaded)
+ calc_extent = _booltype(calc_extent)
+ _apply(f, TraitTarget(target), geom; threaded, calc_extent, kw...)
+end
Call _apply again with the trait of geom
julia
@inline _apply(f::F, target, geom; kw...) where F =
+ _apply(f, target, GI.trait(geom), geom; kw...)
There is no trait and this is an AbstractArray - so just iterate over it calling _apply on the contents
julia
@inline function _apply(f::F, target, ::Nothing, A::AbstractArray; threaded, kw...) where F
For an Array there is nothing else to do but map _apply over all values _maptasks may run this level threaded if threaded==true, but deeper _apply called in the closure will not be threaded
There is no trait and this is not an AbstractArray. Try to call _apply over it. We can't use threading as we don't know if we can can index into it. So just map.
julia
@inline function _apply(f::F, target, ::Nothing, iterable::IterableType; threaded, kw...) where {F, IterableType}
Try the Tables.jl interface first
julia
if Tables.istable(iterable)
+ _apply_table(f, target, iterable; threaded, kw...)
+ else # this is probably some form of iterable...
+ if threaded isa _True
collect first so we can use threads
julia
_apply(f, target, collect(iterable); threaded, kw...)
+ else
+ apply_to_iterable(x) = _apply(f, target, x; kw...)
+ map(apply_to_iterable, iterable)
+ end
+ end
+end
+#=
+Doing this inline in \`_apply\` is _heavily_ type unstable, so it's best to separate this
+by a function barrier.
+
+This function operates \`apply\` on the \`geometry\` column of the table, and returns a new table
+with the same schema, but with the new geometry column.
+
+This new table may be of the same type as the old one iff \`Tables.materializer\` is defined for
+that table. If not, then a \`NamedTuple\` is returned.
+=#
+function _apply_table(f::F, target, iterable::IterableType; threaded, kw...) where {F, IterableType}
+ _get_col_pair(colname) = colname => Tables.getcolumn(iterable, colname)
We extract the geometry column and run apply on it.
Return a new geometryof the same trait as geom, holding the new geoms with crs
julia
return rebuild(geom, geoms; crs)
+end
Fail loudly if we hit PointTrait without running f (after PointTrait there is no further to dig with _apply) @inline _apply(f, ::TraitTarget{Target}, trait::GI.PointTrait, geom; crs=nothing, kw...) where Target = throw(ArgumentError("target Target not found, but reached a PointTrait leaf")) Finally, these short methods are the main purpose of apply. The Trait is a subtype of the Target (or identical to it) So the Target is found. We apply f to geom and return it to previous _apply calls to be wrapped with the outer geometries/feature/featurecollection/array.
julia
_apply(f::F, ::TraitTarget{Target}, ::Trait, geom; crs=GI.crs(geom), kw...) where {F,Target,Trait<:Target} = f(geom)
Define some specific cases of this match to avoid method ambiguity
julia
for T in (
+ GI.PointTrait, GI.LinearRing, GI.LineString,
+ GI.MultiPoint, GI.FeatureTrait, GI.FeatureCollectionTrait
+)
+ @eval _apply(f::F, target::TraitTarget{<:$T}, trait::$T, x; kw...) where F = f(x)
+end
+
+"""
+ applyreduce(f, op, target::Union{TraitTarget, GI.AbstractTrait}, obj; threaded)
+
+Apply function \`f\` to all objects with the \`target\` trait,
+and reduce the result with an \`op\` like \`+\`.
+
+The order and grouping of application of \`op\` is not guaranteed.
+
+If \`threaded==true\` threads will be used over arrays and iterables,
+feature collections and nested geometries.
+"""
+@inline function applyreduce(
+ f::F, op::O, target, geom; threaded=false, init=nothing
+) where {F, O}
+ threaded = _booltype(threaded)
+ _applyreduce(f, op, TraitTarget(target), geom; threaded, init)
+end
+
+@inline _applyreduce(f::F, op::O, target, geom; threaded, init) where {F, O} =
+ _applyreduce(f, op, target, GI.trait(geom), geom; threaded, init)
@inline function _applyreduce(f::F, op::O, ::TraitTarget{Target}, ::Trait, x; kw...) where {F,O,Target,Trait<:Target}
+ f(x)
+end
Fail if we hit PointTrait _applyreduce(f, op, target::TraitTarget{Target}, trait::PointTrait, geom; kw...) where Target = throw(ArgumentError("target target not found")) Specific cases to avoid method ambiguity
julia
for T in (
+ GI.PointTrait, GI.LinearRing, GI.LineString,
+ GI.MultiPoint, GI.FeatureTrait, GI.FeatureCollectionTrait
+)
+ @eval _applyreduce(f::F, op::O, ::TraitTarget{<:$T}, trait::$T, x; kw...) where {F, O} = f(x)
+end
+
+"""
+ unwrap(target::Type{<:AbstractTrait}, obj)
+ unwrap(f, target::Type{<:AbstractTrait}, obj)
+
+Unwrap the object to vectors, down to the target trait.
+
+If \`f\` is passed in it will be applied to the target geometries
+as they are found.
+"""
+function unwrap end
+unwrap(target::Type, geom) = unwrap(identity, target, geom)
unwrap(f, ::Type{Target}, ::Trait, geom) where {Target,Trait<:Target} = f(geom)
Fail if we hit PointTrait
julia
unwrap(f, target::Type, trait::GI.PointTrait, geom) =
+ throw(ArgumentError("target $target not found, but reached a \`PointTrait\` leaf"))
Specific cases to avoid method ambiguity
julia
unwrap(f, target::Type{GI.PointTrait}, trait::GI.PointTrait, geom) = f(geom)
+unwrap(f, target::Type{GI.FeatureTrait}, ::GI.FeatureTrait, feature) = f(feature)
+unwrap(f, target::Type{GI.FeatureCollectionTrait}, ::GI.FeatureCollectionTrait, fc) = f(fc)
+
+"""
+ flatten(target::Type{<:GI.AbstractTrait}, obj)
+ flatten(f, target::Type{<:GI.AbstractTrait}, obj)
+
+Lazily flatten any \`AbstractArray\`, iterator, \`FeatureCollectionTrait\`,
+\`FeatureTrait\` or \`AbstractGeometryTrait\` object \`obj\`, so that objects
+with the \`target\` trait are returned by the iterator.
+
+If \`f\` is passed in it will be applied to the target geometries.
+"""
+flatten(::Type{Target}, geom) where {Target<:GI.AbstractTrait} = flatten(identity, Target, geom)
+flatten(f, ::Type{Target}, geom) where {Target<:GI.AbstractTrait} = _flatten(f, Target, geom)
+
+_flatten(f, ::Type{Target}, geom) where Target = _flatten(f, Target, GI.trait(geom), geom)
_flatten(f, ::Type{Target}, trait::GI.PointTrait, geom) where Target =
+ throw(ArgumentError("target $Target not found, but reached a \`PointTrait\` leaf"))
Specific cases to avoid method ambiguity
julia
_flatten(f, ::Type{<:GI.PointTrait}, ::GI.PointTrait, geom) = (f(geom),)
+_flatten(f, ::Type{<:GI.FeatureTrait}, ::GI.FeatureTrait, feature) = (f(feature),)
+_flatten(f, ::Type{<:GI.FeatureCollectionTrait}, ::GI.FeatureCollectionTrait, fc) = (f(fc),)
+
+
+"""
+ reconstruct(geom, components)
+
+Reconstruct \`geom\` from an iterable of component objects that match its structure.
+
+All objects in \`components\` must have the same \`GeoInterface.trait\`.
+
+Ususally used in combination with \`flatten\`.
+"""
+function reconstruct(geom, components)
+ obj, iter = _reconstruct(geom, components)
+ return obj
+end
+
+_reconstruct(geom, components) =
+ _reconstruct(typeof(GI.trait(first(components))), geom, components, 1)
+_reconstruct(::Type{Target}, geom, components, iter) where Target =
+ _reconstruct(Target, GI.trait(geom), geom, components, iter)
Try to reconstruct over iterables
julia
function _reconstruct(::Type{Target}, ::Nothing, iterable, components, iter) where Target
+ vect = map(iterable) do x
iter is updated by _reconstruct here
julia
obj, iter = _reconstruct(Target, x, components, iter)
+ obj
+ end
+ return vect, iter
+end
Reconstruct feature collections
julia
function _reconstruct(::Type{Target}, ::GI.FeatureCollectionTrait, fc, components, iter) where Target
+ features = map(GI.getfeature(fc)) do feature
iter is updated by _reconstruct here
julia
newfeature, iter = _reconstruct(Target, feature, components, iter)
+ newfeature
+ end
+ return GI.FeatureCollection(features; crs=GI.crs(fc)), iter
+end
+function _reconstruct(::Type{Target}, ::GI.FeatureTrait, feature, components, iter) where Target
+ geom, iter = _reconstruct(Target, GI.geometry(feature), components, iter)
+ return GI.Feature(geom; properties=GI.properties(feature), crs=GI.crs(feature)), iter
+end
+function _reconstruct(::Type{Target}, trait, geom, components, iter) where Target
+ geoms = map(GI.getgeom(geom)) do subgeom
iter is updated by _reconstruct here
julia
subgeom1, iter = _reconstruct(Target, GI.trait(subgeom), subgeom, components, iter)
+ subgeom1
+ end
+ return rebuild(geom, geoms), iter
+end
_reconstruct(::Type{Target}, trait::GI.PointTrait, geom, components, iter) where Target =
+ throw(ArgumentError("target $Target not found, but reached a \`PointTrait\` leaf"))
+
+
+const BasicsGeoms = Union{GB.AbstractGeometry,GB.AbstractFace,GB.AbstractPoint,GB.AbstractMesh,
+ GB.AbstractPolygon,GB.LineString,GB.MultiPoint,GB.MultiLineString,GB.MultiPolygon,GB.Mesh}
+
+"""
+ rebuild(geom, child_geoms)
+
+Rebuild a geometry from child geometries.
+
+By default geometries will be rebuilt as a \`GeoInterface.Wrappers\`
+geometry, but \`rebuild\` can have methods added to it to dispatch
+on geometries from other packages and specify how to rebuild them.
+
+(Maybe it should go into GeoInterface.jl)
+"""
+rebuild(geom, child_geoms; kw...) = rebuild(GI.trait(geom), geom, child_geoms; kw...)
+function rebuild(trait::GI.AbstractTrait, geom, child_geoms; crs=GI.crs(geom), extent=nothing)
+ T = GI.geointerface_geomtype(trait)
+ if GI.is3d(geom)
The Boolean type parameters here indicate "3d-ness" and "measure" coordinate, respectively.
Here we use the compiler directive @assume_effects :foldable to force the compiler to lookup through the closure. This alone makes e.g. flip 2.5x faster!
julia
Base.@assume_effects :foldable @inline function _maptasks(f::F, taskrange, threaded::_False)::Vector where F
+ map(f, taskrange)
+end
Threading utility, modified Mason Protters threading PSA run f over ntasks, where f recieves an AbstractArray/range of linear indices
WARNING: this will not work for mean/median - only ops where grouping is possible
julia
@inline function _mapreducetasks(f::F, op, taskrange, threaded::_True; init) where F
+ ntasks = length(taskrange)
Customize this as needed. More tasks have more overhead, but better load balancing
`,202),e=[h];function l(p,k,r,d,g,E){return a(),i("div",null,e)}const c=s(n,[["render",l]]);export{o as __pageData,c as default};
diff --git a/previews/PR149/assets/source_primitives.md.YB3uDiz_.lean.js b/previews/PR149/assets/source_primitives.md.YB3uDiz_.lean.js
new file mode 100644
index 000000000..a9594741f
--- /dev/null
+++ b/previews/PR149/assets/source_primitives.md.YB3uDiz_.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as t}from"./chunks/framework.CDOaXZPW.js";const o=JSON.parse('{"title":"Primitive functions","description":"","frontmatter":{},"headers":[],"relativePath":"source/primitives.md","filePath":"source/primitives.md","lastUpdated":null}'),n={name:"source/primitives.md"},h=t("",202),e=[h];function l(p,k,r,d,g,E){return a(),i("div",null,e)}const c=s(n,[["render",l]]);export{o as __pageData,c as default};
diff --git a/previews/PR149/assets/source_transformations_correction_closed_ring.md.Btjl6Xno.js b/previews/PR149/assets/source_transformations_correction_closed_ring.md.Btjl6Xno.js
new file mode 100644
index 000000000..1dee9f37d
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_correction_closed_ring.md.Btjl6Xno.js
@@ -0,0 +1,30 @@
+import{_ as t,c as i,j as s,a,a6 as e,o as n}from"./chunks/framework.CDOaXZPW.js";const Q=JSON.parse('{"title":"Closed Rings","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/correction/closed_ring.md","filePath":"source/transformations/correction/closed_ring.md","lastUpdated":null}'),l={name:"source/transformations/correction/closed_ring.md"},h=e(`
A closed ring is a ring that has the same start and end point. This is a requirement for a valid polygon (technically, for a valid LinearRing). This correction is used to ensure that the polygon is valid.
The reason this operates on the polygon level is that several packages are loose about whether they return LinearRings (which is correct) or LineStrings (which is incorrect) for the contents of a polygon. Therefore, we decompose manually to ensure correctness.
Many polygon providers do not close their polygons, which makes them invalid according to the specification. Quite a few geometry algorithms assume that polygons are closed, and leaving them open can lead to incorrect results!
For example, the following polygon is not valid:
julia
import GeoInterface as GI
+polygon = GI.Polygon([[(0, 0), (1, 0), (1, 1), (0, 1)]])
"""
+ ClosedRing() <: GeometryCorrection
+
+This correction ensures that a polygon's exterior and interior rings are closed.
+
+It can be called on any geometry correction as usual.
+
+See also \`GeometryCorrection\`.
+"""
+struct ClosedRing <: GeometryCorrection end
+
+application_level(::ClosedRing) = GI.PolygonTrait
+
+function (::ClosedRing)(::GI.PolygonTrait, polygon)
+ exterior = _close_linear_ring(GI.getexterior(polygon))
+
+ holes = map(GI.gethole(polygon)) do hole
+ _close_linear_ring(hole) # TODO: make this more efficient, or use tuples!
+ end
+
+ return GI.Wrappers.Polygon([exterior, holes...])
+end
+
+function _close_linear_ring(ring)
+ if GI.getpoint(ring, 1) == GI.getpoint(ring, GI.npoint(ring))
`,12);function m(C,_,v,T,b,x){return n(),i("div",null,[h,s("p",null,[a("You can see that the last point of the ring here is equal to the first point. For a polygon with "),s("mjx-container",p,[(n(),i("svg",k,o)),d]),a(" sides, there should be "),s("mjx-container",g,[(n(),i("svg",c,y)),u]),a(" vertices.")]),F])}const A=t(l,[["render",m]]);export{Q as __pageData,A as default};
diff --git a/previews/PR149/assets/source_transformations_correction_closed_ring.md.Btjl6Xno.lean.js b/previews/PR149/assets/source_transformations_correction_closed_ring.md.Btjl6Xno.lean.js
new file mode 100644
index 000000000..3c7865c6c
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_correction_closed_ring.md.Btjl6Xno.lean.js
@@ -0,0 +1 @@
+import{_ as t,c as i,j as s,a,a6 as e,o as n}from"./chunks/framework.CDOaXZPW.js";const Q=JSON.parse('{"title":"Closed Rings","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/correction/closed_ring.md","filePath":"source/transformations/correction/closed_ring.md","lastUpdated":null}'),l={name:"source/transformations/correction/closed_ring.md"},h=e("",12),p={class:"MathJax",jax:"SVG",style:{direction:"ltr",position:"relative"}},k={style:{overflow:"visible","min-height":"1px","min-width":"1px","vertical-align":"-0.025ex"},xmlns:"http://www.w3.org/2000/svg",width:"1.357ex",height:"1.025ex",role:"img",focusable:"false",viewBox:"0 -442 600 453","aria-hidden":"true"},r=s("g",{stroke:"currentColor",fill:"currentColor","stroke-width":"0",transform:"scale(1,-1)"},[s("g",{"data-mml-node":"math"},[s("g",{"data-mml-node":"mi"},[s("path",{"data-c":"1D45B",d:"M21 287Q22 293 24 303T36 341T56 388T89 425T135 442Q171 442 195 424T225 390T231 369Q231 367 232 367L243 378Q304 442 382 442Q436 442 469 415T503 336T465 179T427 52Q427 26 444 26Q450 26 453 27Q482 32 505 65T540 145Q542 153 560 153Q580 153 580 145Q580 144 576 130Q568 101 554 73T508 17T439 -10Q392 -10 371 17T350 73Q350 92 386 193T423 345Q423 404 379 404H374Q288 404 229 303L222 291L189 157Q156 26 151 16Q138 -11 108 -11Q95 -11 87 -5T76 7T74 17Q74 30 112 180T152 343Q153 348 153 366Q153 405 129 405Q91 405 66 305Q60 285 60 284Q58 278 41 278H27Q21 284 21 287Z",style:{"stroke-width":"3"}})])])],-1),o=[r],d=s("mjx-assistive-mml",{unselectable:"on",display:"inline",style:{top:"0px",left:"0px",clip:"rect(1px, 1px, 1px, 1px)","-webkit-touch-callout":"none","-webkit-user-select":"none","-khtml-user-select":"none","-moz-user-select":"none","-ms-user-select":"none","user-select":"none",position:"absolute",padding:"1px 0px 0px 0px",border:"0px",display:"block",width:"auto",overflow:"hidden"}},[s("math",{xmlns:"http://www.w3.org/1998/Math/MathML"},[s("mi",null,"n")])],-1),g={class:"MathJax",jax:"SVG",style:{direction:"ltr",position:"relative"}},c={style:{overflow:"visible","min-height":"1px","min-width":"1px","vertical-align":"-0.186ex"},xmlns:"http://www.w3.org/2000/svg",width:"5.254ex",height:"1.692ex",role:"img",focusable:"false",viewBox:"0 -666 2322.4 748","aria-hidden":"true"},E=e("",1),y=[E],u=s("mjx-assistive-mml",{unselectable:"on",display:"inline",style:{top:"0px",left:"0px",clip:"rect(1px, 1px, 1px, 1px)","-webkit-touch-callout":"none","-webkit-user-select":"none","-khtml-user-select":"none","-moz-user-select":"none","-ms-user-select":"none","user-select":"none",position:"absolute",padding:"1px 0px 0px 0px",border:"0px",display:"block",width:"auto",overflow:"hidden"}},[s("math",{xmlns:"http://www.w3.org/1998/Math/MathML"},[s("mi",null,"n"),s("mo",null,"+"),s("mn",null,"1")])],-1),F=e("",12);function m(C,_,v,T,b,x){return n(),i("div",null,[h,s("p",null,[a("You can see that the last point of the ring here is equal to the first point. For a polygon with "),s("mjx-container",p,[(n(),i("svg",k,o)),d]),a(" sides, there should be "),s("mjx-container",g,[(n(),i("svg",c,y)),u]),a(" vertices.")]),F])}const A=t(l,[["render",m]]);export{Q as __pageData,A as default};
diff --git a/previews/PR149/assets/source_transformations_correction_geometry_correction.md.ENcozR8K.js b/previews/PR149/assets/source_transformations_correction_geometry_correction.md.ENcozR8K.js
new file mode 100644
index 000000000..4e38b9e02
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_correction_geometry_correction.md.ENcozR8K.js
@@ -0,0 +1,31 @@
+import{_ as i,c as s,o as e,a6 as t}from"./chunks/framework.CDOaXZPW.js";const g=JSON.parse('{"title":"Geometry Corrections","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/correction/geometry_correction.md","filePath":"source/transformations/correction/geometry_correction.md","lastUpdated":null}'),a={name:"source/transformations/correction/geometry_correction.md"},n=t(`
All GeometryCorrections are callable structs which, when called, apply the correction to the given geometry, and return either a copy or the original geometry (if nothing needed to be corrected).
This abstract type represents a geometry correction.
Interface
Any GeometryCorrection must implement two functions: * application_level(::GeometryCorrection)::AbstractGeometryTrait: This function should return the GeoInterface trait that the correction is intended to be applied to, like PointTrait or LineStringTrait or PolygonTrait. * (::GeometryCorrection)(::AbstractGeometryTrait, geometry)::(some_geometry): This function should apply the correction to the given geometry, and return a new geometry.
Any geometry correction must implement the interface as given above.
julia
"""
+ abstract type GeometryCorrection
+
+This abstract type represents a geometry correction.
+
+# Interface
+
+Any \`GeometryCorrection\` must implement two functions:
+ * \`application_level(::GeometryCorrection)::AbstractGeometryTrait\`: This function should return the \`GeoInterface\` trait that the correction is intended to be applied to, like \`PointTrait\` or \`LineStringTrait\` or \`PolygonTrait\`.
+ * \`(::GeometryCorrection)(::AbstractGeometryTrait, geometry)::(some_geometry)\`: This function should apply the correction to the given geometry, and return a new geometry.
+"""
+abstract type GeometryCorrection end
+
+application_level(gc::GeometryCorrection) = error("Not implemented yet for $(gc)")
+
+(gc::GeometryCorrection)(geometry) = gc(GI.trait(geometry), geometry)
+
+(gc::GeometryCorrection)(trait::GI.AbstractGeometryTrait, geometry) = error("Not implemented yet for $(gc) and $(trait).")
+
+function fix(geometry; corrections = GeometryCorrection[ClosedRing(),], kwargs...)
+ traits = application_level.(corrections)
+ final_geometry = geometry
+ for Trait in (GI.PointTrait, GI.MultiPointTrait, GI.LineStringTrait, GI.LinearRingTrait, GI.MultiLineStringTrait, GI.PolygonTrait, GI.MultiPolygonTrait)
+ available_corrections = findall(x -> x == Trait, traits)
+ isempty(available_corrections) && continue
+ @debug "Correcting for $(Trait)"
+ net_function = reduce(∘, corrections[available_corrections])
+ final_geometry = apply(net_function, Trait, final_geometry; kwargs...)
+ end
+ return final_geometry
+end
This correction ensures that the polygons included in a multipolygon aren't intersecting. If any polygon's are intersecting, they will be made nonintersecting through the difference operation to create a unique set of disjoint (other than potentially connections by a single point) polygons covering the same area. See also GeometryCorrection, UnionIntersectingPolygons.
This abstract type represents a geometry correction.
Interface
Any GeometryCorrection must implement two functions: * application_level(::GeometryCorrection)::AbstractGeometryTrait: This function should return the GeoInterface trait that the correction is intended to be applied to, like PointTrait or LineStringTrait or PolygonTrait. * (::GeometryCorrection)(::AbstractGeometryTrait, geometry)::(some_geometry): This function should apply the correction to the given geometry, and return a new geometry.
This correction ensures that the polygon's included in a multipolygon aren't intersecting. If any polygon's are intersecting, they will be combined through the union operation to create a unique set of disjoint (other than potentially connections by a single point) polygons covering the same area.
`,23),r=[n];function o(l,p,h,c,k,d){return e(),s("div",null,r)}const m=i(a,[["render",o]]);export{g as __pageData,m as default};
diff --git a/previews/PR149/assets/source_transformations_correction_geometry_correction.md.ENcozR8K.lean.js b/previews/PR149/assets/source_transformations_correction_geometry_correction.md.ENcozR8K.lean.js
new file mode 100644
index 000000000..4d1aaa9d9
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_correction_geometry_correction.md.ENcozR8K.lean.js
@@ -0,0 +1 @@
+import{_ as i,c as s,o as e,a6 as t}from"./chunks/framework.CDOaXZPW.js";const g=JSON.parse('{"title":"Geometry Corrections","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/correction/geometry_correction.md","filePath":"source/transformations/correction/geometry_correction.md","lastUpdated":null}'),a={name:"source/transformations/correction/geometry_correction.md"},n=t("",23),r=[n];function o(l,p,h,c,k,d){return e(),s("div",null,r)}const m=i(a,[["render",o]]);export{g as __pageData,m as default};
diff --git a/previews/PR149/assets/source_transformations_correction_intersecting_polygons.md.oBuwteZE.js b/previews/PR149/assets/source_transformations_correction_intersecting_polygons.md.oBuwteZE.js
new file mode 100644
index 000000000..553831f7e
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_correction_intersecting_polygons.md.oBuwteZE.js
@@ -0,0 +1,97 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Intersecting Polygons","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/correction/intersecting_polygons.md","filePath":"source/transformations/correction/intersecting_polygons.md","lastUpdated":null}'),l={name:"source/transformations/correction/intersecting_polygons.md"},t=n(`
If the sub-polygons of a multipolygon are intersecting, this makes them invalid according to specification. Each sub-polygon of a multipolygon being disjoint (other than by a single point) is a requirment for a valid multipolygon. However, different libraries may achieve this in different ways.
For example, taking the union of all sub-polygons of a multipolygon will create a new multipolygon where each sub-polygon is disjoint. This can be done with the UnionIntersectingPolygons correction.
The reason this operates on a multipolygon level is that it is easy for users to mistakenly create multipolygon's that overlap, which can then be detrimental to polygon clipping performance and even create wrong answers.
Multipolygon providers may not check that the polygons making up their multipolygons do not intersect, which makes them invalid according to the specification.
For example, the following multipolygon is not valid:
julia
import GeoInterface as GI
+polygon = GI.Polygon([[(0.0, 0.0), (3.0, 0.0), (3.0, 3.0), (0.0, 3.0), (0.0, 0.0)]])
+multipolygon = GI.MultiPolygon([polygon, polygon])
"""
+ UnionIntersectingPolygons() <: GeometryCorrection
+
+This correction ensures that the polygon's included in a multipolygon aren't intersecting.
+If any polygon's are intersecting, they will be combined through the union operation to
+create a unique set of disjoint (other than potentially connections by a single point)
+polygons covering the same area.
+
+See also \`GeometryCorrection\`.
+"""
+struct UnionIntersectingPolygons <: GeometryCorrection end
+
+application_level(::UnionIntersectingPolygons) = GI.MultiPolygonTrait
+
+function (::UnionIntersectingPolygons)(::GI.MultiPolygonTrait, multipoly)
+ union_multipoly = tuples(multipoly)
+ n_polys = GI.npolygon(multipoly)
+ if n_polys > 1
+ keep_idx = trues(n_polys) # keep track of sub-polygons to remove
Combine any sub-polygons that intersect
julia
for (curr_idx, _) in Iterators.filter(last, Iterators.enumerate(keep_idx))
+ curr_poly = union_multipoly.geom[curr_idx]
+ poly_disjoint = false
+ while !poly_disjoint
+ poly_disjoint = true # assume current polygon is disjoint from others
+ for (next_idx, _) in Iterators.filter(last, Iterators.drop(Iterators.enumerate(keep_idx), curr_idx))
+ next_poly = union_multipoly.geom[next_idx]
+ if intersects(curr_poly, next_poly) # if two polygons intersect
+ new_polys = union(curr_poly, next_poly; target = GI.PolygonTrait())
+ n_new_polys = length(new_polys)
+ if n_new_polys == 1 # if polygons combined
+ poly_disjoint = false
+ union_multipoly.geom[curr_idx] = new_polys[1]
+ curr_poly = union_multipoly.geom[curr_idx]
+ keep_idx[next_idx] = false
+ end
+ end
+ end
+ end
+ end
+ keepat!(union_multipoly.geom, keep_idx)
+ end
+ return union_multipoly
+end
+
+"""
+ DiffIntersectingPolygons() <: GeometryCorrection
+This correction ensures that the polygons included in a multipolygon aren't intersecting.
+If any polygon's are intersecting, they will be made nonintersecting through the \`difference\`
+operation to create a unique set of disjoint (other than potentially connections by a single point)
+polygons covering the same area.
+See also \`GeometryCorrection\`, \`UnionIntersectingPolygons\`.
+"""
+struct DiffIntersectingPolygons <: GeometryCorrection end
+
+application_level(::DiffIntersectingPolygons) = GI.MultiPolygonTrait
+
+function (::DiffIntersectingPolygons)(::GI.MultiPolygonTrait, multipoly)
+ diff_multipoly = tuples(multipoly)
+ n_starting_polys = GI.npolygon(multipoly)
+ n_polys = n_starting_polys
+ if n_polys > 1
+ keep_idx = trues(n_polys) # keep track of sub-polygons to remove
Break apart any sub-polygons that intersect
julia
for curr_idx in 1:n_starting_polys
+ !keep_idx[curr_idx] && continue
+ for next_idx in (curr_idx + 1):n_starting_polys
+ !keep_idx[next_idx] && continue
+ next_poly = diff_multipoly.geom[next_idx]
+ n_new_polys = 0
+ curr_pieces_added = (n_polys + 1):(n_polys + n_new_polys)
+ for curr_piece_idx in Iterators.flatten((curr_idx:curr_idx, curr_pieces_added))
+ !keep_idx[curr_piece_idx] && continue
+ curr_poly = diff_multipoly.geom[curr_piece_idx]
+ if intersects(curr_poly, next_poly) # if two polygons intersect
+ new_polys = difference(curr_poly, next_poly; target = GI.PolygonTrait())
+ n_new_pieces = length(new_polys) - 1
+ if n_new_pieces < 0 # current polygon is covered by next_polygon
+ keep_idx[curr_piece_idx] = false
+ break
+ elseif n_new_pieces ≥ 0
+ diff_multipoly.geom[curr_piece_idx] = new_polys[1]
+ curr_poly = diff_multipoly.geom[curr_piece_idx]
+ if n_new_pieces > 0 # current polygon breaks into several pieces
+ append!(diff_multipoly.geom, @view new_polys[2:end])
+ append!(keep_idx, trues(n_new_pieces))
+ n_new_polys += n_new_pieces
+ end
+ end
+ end
+ end
+ n_polys += n_new_polys
+ end
+ end
+ keepat!(diff_multipoly.geom, keep_idx)
+ end
+ return diff_multipoly
+end
`,22),h=[t];function p(e,k,r,g,o,E){return a(),i("div",null,h)}const c=s(l,[["render",p]]);export{y as __pageData,c as default};
diff --git a/previews/PR149/assets/source_transformations_correction_intersecting_polygons.md.oBuwteZE.lean.js b/previews/PR149/assets/source_transformations_correction_intersecting_polygons.md.oBuwteZE.lean.js
new file mode 100644
index 000000000..bbda9450e
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_correction_intersecting_polygons.md.oBuwteZE.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Intersecting Polygons","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/correction/intersecting_polygons.md","filePath":"source/transformations/correction/intersecting_polygons.md","lastUpdated":null}'),l={name:"source/transformations/correction/intersecting_polygons.md"},t=n("",22),h=[t];function p(e,k,r,g,o,E){return a(),i("div",null,h)}const c=s(l,[["render",p]]);export{y as __pageData,c as default};
diff --git a/previews/PR149/assets/source_transformations_extent.md.oK1PYPta.js b/previews/PR149/assets/source_transformations_extent.md.oK1PYPta.js
new file mode 100644
index 000000000..58c1b659f
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_extent.md.oK1PYPta.js
@@ -0,0 +1,13 @@
+import{_ as s,c as e,o as a,a6 as t}from"./chunks/framework.CDOaXZPW.js";const u=JSON.parse('{"title":"Extent embedding","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/extent.md","filePath":"source/transformations/extent.md","lastUpdated":null}'),n={name:"source/transformations/extent.md"},i=t(`
"""
+ embed_extent(obj)
+
+Recursively wrap the object with a GeoInterface.jl geometry,
+calculating and adding an \`Extents.Extent\` to all objects.
+
+This can improve performance when extents need to be checked multiple times,
+such when needing to check if many points are in geometries, and using their extents
+as a quick filter for obviously exterior points.
`,6),l=[i];function p(r,h,d,o,c,k){return a(),e("div",null,l)}const m=s(n,[["render",p]]);export{u as __pageData,m as default};
diff --git a/previews/PR149/assets/source_transformations_extent.md.oK1PYPta.lean.js b/previews/PR149/assets/source_transformations_extent.md.oK1PYPta.lean.js
new file mode 100644
index 000000000..ab3a31b17
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_extent.md.oK1PYPta.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as e,o as a,a6 as t}from"./chunks/framework.CDOaXZPW.js";const u=JSON.parse('{"title":"Extent embedding","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/extent.md","filePath":"source/transformations/extent.md","lastUpdated":null}'),n={name:"source/transformations/extent.md"},i=t("",6),l=[i];function p(r,h,d,o,c,k){return a(),e("div",null,l)}const m=s(n,[["render",p]]);export{u as __pageData,m as default};
diff --git a/previews/PR149/assets/source_transformations_flip.md.DYA-PJ96.js b/previews/PR149/assets/source_transformations_flip.md.DYA-PJ96.js
new file mode 100644
index 000000000..968b7568b
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_flip.md.DYA-PJ96.js
@@ -0,0 +1,22 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Coordinate flipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/flip.md","filePath":"source/transformations/flip.md","lastUpdated":null}'),p={name:"source/transformations/flip.md"},t=n(`
This is a simple example of how to use the apply functionality in a function, by flipping the x and y coordinates of a geometry.
julia
"""
+ flip(obj)
+
+Swap all of the x and y coordinates in obj, otherwise
+keeping the original structure (but not necessarily the
+original type).
+
+# Keywords
+
+$APPLY_KEYWORDS
+"""
+function flip(geom; kw...)
+ if _is3d(geom)
+ return apply(PointTrait(), geom; kw...) do p
+ (GI.y(p), GI.x(p), GI.z(p))
+ end
+ else
+ return apply(PointTrait(), geom; kw...) do p
+ (GI.y(p), GI.x(p))
+ end
+ end
+end
`,5),l=[t];function h(e,k,r,d,o,g){return a(),i("div",null,l)}const c=s(p,[["render",h]]);export{y as __pageData,c as default};
diff --git a/previews/PR149/assets/source_transformations_flip.md.DYA-PJ96.lean.js b/previews/PR149/assets/source_transformations_flip.md.DYA-PJ96.lean.js
new file mode 100644
index 000000000..39cd24ffe
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_flip.md.DYA-PJ96.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Coordinate flipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/flip.md","filePath":"source/transformations/flip.md","lastUpdated":null}'),p={name:"source/transformations/flip.md"},t=n("",5),l=[t];function h(e,k,r,d,o,g){return a(),i("div",null,l)}const c=s(p,[["render",h]]);export{y as __pageData,c as default};
diff --git a/previews/PR149/assets/source_transformations_reproject.md.BblwwKZt.js b/previews/PR149/assets/source_transformations_reproject.md.BblwwKZt.js
new file mode 100644
index 000000000..a957250d7
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_reproject.md.BblwwKZt.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as e}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Geometry reprojection","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/reproject.md","filePath":"source/transformations/reproject.md","lastUpdated":null}'),n={name:"source/transformations/reproject.md"},t=e('
This file is pretty simple - it simply reprojects a geometry pointwise from one CRS to another. It uses the Proj package for the transformation, but this could be moved to an extension if needed.
Note that the actual implementation is in the GeometryOpsProjExt extension module.
This works using the apply functionality.
julia
"""\n reproject(geometry; source_crs, target_crs, transform, always_xy, time)\n reproject(geometry, source_crs, target_crs; always_xy, time)\n reproject(geometry, transform; always_xy, time)\n\nReproject any GeoInterface.jl compatible `geometry` from `source_crs` to `target_crs`.\n\nThe returned object will be constructed from `GeoInterface.WrapperGeometry`\ngeometries, wrapping views of a `Vector{Proj.Point{D}}`, where `D` is the dimension.\n\n!!! tip\n The `Proj.jl` package must be loaded for this method to work,\n since it is implemented in a package extension.\n\n# Arguments\n\n- `geometry`: Any GeoInterface.jl compatible geometries.\n- `source_crs`: the source coordinate referece system, as a GeoFormatTypes.jl object or a string.\n- `target_crs`: the target coordinate referece system, as a GeoFormatTypes.jl object or a string.\n\nIf these a passed as keywords, `transform` will take priority.\nWithout it `target_crs` is always needed, and `source_crs` is\nneeded if it is not retreivable from the geometry with `GeoInterface.crs(geometry)`.\n\n# Keywords\n\n- `always_xy`: force x, y coordinate order, `true` by default.\n `false` will expect and return points in the crs coordinate order.\n- `time`: the time for the coordinates. `Inf` by default.\n$APPLY_KEYWORDS\n"""\nfunction reproject end
We also inject a method error handler, which prints a suggestion if the Proj extension is not loaded.
julia
function _reproject_error_hinter(io, exc, argtypes, kwargs)\n if isnothing(Base.get_extension(GeometryOps, :GeometryOpsProjExt)) && exc.f == reproject\n print(io, "\\n\\nThe `reproject` method requires the Proj.jl package to be explicitly loaded.\\n")\n print(io, "You can do this by simply typing ")\n printstyled(io, "using Proj"; color = :cyan, bold = true)\n println(io, " in your REPL, \\nor otherwise loading Proj.jl via using or import.")\n else # this is a more general error\n nothing\n end\nend
',11),p=[t];function l(r,h,o,k,d,c){return a(),i("div",null,p)}const F=s(n,[["render",l]]);export{y as __pageData,F as default};
diff --git a/previews/PR149/assets/source_transformations_reproject.md.BblwwKZt.lean.js b/previews/PR149/assets/source_transformations_reproject.md.BblwwKZt.lean.js
new file mode 100644
index 000000000..fb8c0e057
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_reproject.md.BblwwKZt.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as e}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Geometry reprojection","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/reproject.md","filePath":"source/transformations/reproject.md","lastUpdated":null}'),n={name:"source/transformations/reproject.md"},t=e("",11),p=[t];function l(r,h,o,k,d,c){return a(),i("div",null,p)}const F=s(n,[["render",l]]);export{y as __pageData,F as default};
diff --git a/previews/PR149/assets/source_transformations_segmentize.md.ok_mERf1.js b/previews/PR149/assets/source_transformations_segmentize.md.ok_mERf1.js
new file mode 100644
index 000000000..bc2abd4dd
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_segmentize.md.ok_mERf1.js
@@ -0,0 +1,154 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/gjrlysw.BOOG5oTW.png",t="/GeometryOps.jl/previews/PR149/assets/luasozu.C4Hz5np8.png",c=JSON.parse('{"title":"Segmentize","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/segmentize.md","filePath":"source/transformations/segmentize.md","lastUpdated":null}'),e={name:"source/transformations/segmentize.md"},l=n(`
This function "segmentizes" or "densifies" a geometry by adding extra vertices to the geometry so that no segment is longer than a given distance. This is useful for plotting geometries with a limited number of vertices, or for ensuring that a geometry is not too "coarse" for a given application.
Info
We plan to add interpolated segmentization from DataInterpolations.jl in the future, which will be available to any vector of point-like objects.
For now, this function only works on 2D geometries. We will also support 3D geometries, as well as measure interpolation, in the future.
# These are initial distances, which yield similar numbers of points
+# in the final geometry.
+init_lin = 0.01
+init_geo = 900
+
+# LibGEOS.jl doesn't offer this function, so we just wrap it ourselves!
+function densify(obj::LG.Geometry, tol::Real, context::LG.GEOSContext = LG.get_context(obj))
+ result = LG.GEOSDensify_r(context, obj, tol)
+ if result == C_NULL
+ error("LibGEOS: Error in GEOSDensify")
+ end
+ LG.geomFromGEOS(result, context)
+end
+# now, we get to the actual benchmarking:
+for scalefactor in exp10.(LinRange(log10(0.1), log10(10), 5))
+ lin_dist = init_lin * scalefactor
+ geo_dist = init_geo * scalefactor
+
+ npoints_linear = GI.npoint(GO.segmentize(rectangle; max_distance = lin_dist))
+ npoints_geodesic = GO.segmentize(GO.GeodesicSegments(; max_distance = geo_dist), rectangle) |> GI.npoint
+ npoints_libgeos = GI.npoint(densify(lg_rectangle, lin_dist))
+
+ segmentize_suite["Linear"][npoints_linear] = @be GO.segmentize(GO.LinearSegments(; max_distance = $lin_dist), $rectangle) seconds=1
+ segmentize_suite["Geodesic"][npoints_geodesic] = @be GO.segmentize(GO.GeodesicSegments(; max_distance = $geo_dist), $rectangle) seconds=1
+ segmentize_suite["LibGEOS"][npoints_libgeos] = @be densify($lg_rectangle, $lin_dist) seconds=1
+
+end
+
+plot_trials(segmentize_suite)
julia
abstract type SegmentizeMethod end
+"""
+ LinearSegments(; max_distance::Real)
+
+A method for segmentizing geometries by adding extra vertices to the geometry so that no segment is longer than a given distance.
+
+Here, \`max_distance\` is a purely nondimensional quantity and will apply in the input space. This is to say, that if the polygon is
+provided in lat/lon coordinates then the \`max_distance\` will be in degrees of arc. If the polygon is provided in meters, then the
+\`max_distance\` will be in meters.
+"""
+Base.@kwdef struct LinearSegments <: SegmentizeMethod
+ max_distance::Float64
+end
+
+"""
+ GeodesicSegments(; max_distance::Real, equatorial_radius::Real=6378137, flattening::Real=1/298.257223563)
+
+A method for segmentizing geometries by adding extra vertices to the geometry so that no segment is longer than a given distance.
+This method calculates the distance between points on the geodesic, and assumes input in lat/long coordinates.
+
+!!! warning
+ Any input geometries must be in lon/lat coordinates! If not, the method may fail or error.
+
+# Arguments
+- \`max_distance::Real\`: The maximum distance, **in meters**, between vertices in the geometry.
+- \`equatorial_radius::Real=6378137\`: The equatorial radius of the Earth, in meters. Passed to \`Proj.geod_geodesic\`.
+- \`flattening::Real=1/298.257223563\`: The flattening of the Earth, which is the ratio of the difference between the equatorial and polar radii to the equatorial radius. Passed to \`Proj.geod_geodesic\`.
+
+One can also omit the \`equatorial_radius\` and \`flattening\` keyword arguments, and pass a \`geodesic\` object directly to the eponymous keyword.
+
+This method uses the Proj/GeographicLib API for geodesic calculations.
+"""
+struct GeodesicSegments{T} <: SegmentizeMethod
+ geodesic::T# ::Proj.geod_geodesic
+ max_distance::Float64
+end
Add an error hint for GeodesicSegments if Proj is not loaded!
julia
function _geodesic_segments_error_hinter(io, exc, argtypes, kwargs)
+ if isnothing(Base.get_extension(GeometryOps, :GeometryOpsProjExt)) && exc.f == GeodesicSegments
+ print(io, "\\n\\nThe \`GeodesicSegments\` method requires the Proj.jl package to be explicitly loaded.\\n")
+ print(io, "You can do this by simply typing ")
+ printstyled(io, "using Proj"; color = :cyan, bold = true)
+ println(io, " in your REPL, \\nor otherwise loading Proj.jl via using or import.")
+ end
+end
"""
+ segmentize([method = LinearSegments()], geom; max_distance::Real, threaded)
+
+Segmentize a geometry by adding extra vertices to the geometry so that no segment is longer than a given distance.
+This is useful for plotting geometries with a limited number of vertices, or for ensuring that a geometry is not too "coarse" for a given application.
+
+# Arguments
+- \`method::SegmentizeMethod = LinearSegments()\`: The method to use for segmentizing the geometry. At the moment, only \`LinearSegments\` and \`GeodesicSegments\` are available.
+- \`geom\`: The geometry to segmentize. Must be a \`LineString\`, \`LinearRing\`, or greater in complexity.
+- \`max_distance::Real\`: The maximum distance, **in the input space**, between vertices in the geometry. Only used if you don't explicitly pass a \`method\`.
+
+Returns a geometry of similar type to the input geometry, but resampled.
+"""
+function segmentize(geom; max_distance, threaded::Union{Bool, BoolsAsTypes} = _False())
+ return segmentize(LinearSegments(; max_distance), geom; threaded = _booltype(threaded))
+end
+function segmentize(method::SegmentizeMethod, geom; threaded::Union{Bool, BoolsAsTypes} = _False())
+ @assert method.max_distance > 0 "\`max_distance\` should be positive and nonzero! Found $(method.max_distance)."
+ segmentize_function = Base.Fix1(_segmentize, method)
+ return apply(segmentize_function, Union{GI.LinearRingTrait, GI.LineStringTrait}, geom; threaded)
+end
+
+_segmentize(method, geom) = _segmentize(method, geom, GI.trait(geom))
+#=
+This is a method which performs the common functionality for both linear and geodesic algorithms,
+and calls out to the "kernel" function which we've defined per linesegment.
+=#
+function _segmentize(method::Union{LinearSegments, GeodesicSegments}, geom, T::Union{GI.LineStringTrait, GI.LinearRingTrait})
+ first_coord = GI.getpoint(geom, 1)
+ x1, y1 = GI.x(first_coord), GI.y(first_coord)
+ new_coords = NTuple{2, Float64}[]
+ sizehint!(new_coords, GI.npoint(geom))
+ push!(new_coords, (x1, y1))
+ for coord in Iterators.drop(GI.getpoint(geom), 1)
+ x2, y2 = GI.x(coord), GI.y(coord)
+ _fill_linear_kernel!(method, new_coords, x1, y1, x2, y2)
+ x1, y1 = x2, y2
+ end
+ return rebuild(geom, new_coords)
+end
+
+function _fill_linear_kernel!(method::LinearSegments, new_coords::Vector, x1, y1, x2, y2)
+ dx, dy = x2 - x1, y2 - y1
+ distance = hypot(dx, dy) # this is a more stable way to compute the Euclidean distance
+ if distance > method.max_distance
+ n_segments = ceil(Int, distance / method.max_distance)
+ for i in 1:(n_segments - 1)
+ t = i / n_segments
+ push!(new_coords, (x1 + t * dx, y1 + t * dy))
+ end
+ end
End the line with the original coordinate, to avoid any multiplication errors.
julia
push!(new_coords, (x2, y2))
+ return nothing
+end
Note
The _fill_linear_kernel definition for GeodesicSegments is in the GeometryOpsProjExt extension module, in the segmentize.jl file.
`,34),k=[l];function p(r,E,d,g,y,o){return a(),i("div",null,k)}const C=s(e,[["render",p]]);export{c as __pageData,C as default};
diff --git a/previews/PR149/assets/source_transformations_segmentize.md.ok_mERf1.lean.js b/previews/PR149/assets/source_transformations_segmentize.md.ok_mERf1.lean.js
new file mode 100644
index 000000000..1d3fa89e2
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_segmentize.md.ok_mERf1.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/gjrlysw.BOOG5oTW.png",t="/GeometryOps.jl/previews/PR149/assets/luasozu.C4Hz5np8.png",c=JSON.parse('{"title":"Segmentize","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/segmentize.md","filePath":"source/transformations/segmentize.md","lastUpdated":null}'),e={name:"source/transformations/segmentize.md"},l=n("",34),k=[l];function p(r,E,d,g,y,o){return a(),i("div",null,k)}const C=s(e,[["render",p]]);export{c as __pageData,C as default};
diff --git a/previews/PR149/assets/source_transformations_simplify.md.ChtGmeP2.js b/previews/PR149/assets/source_transformations_simplify.md.ChtGmeP2.js
new file mode 100644
index 000000000..9e2161d57
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_simplify.md.ChtGmeP2.js
@@ -0,0 +1,488 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/mvimxvw.Bglvb-jp.png",l="/GeometryOps.jl/previews/PR149/assets/cbtnibw.B94PsR1K.png",k="/GeometryOps.jl/previews/PR149/assets/eouzjij.CXk0JbJI.png",t="/GeometryOps.jl/previews/PR149/assets/awkfodg.CIBNG3Jj.png",u=JSON.parse('{"title":"Geometry simplification","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/simplify.md","filePath":"source/transformations/simplify.md","lastUpdated":null}'),p={name:"source/transformations/simplify.md"},e=n(`
This file holds implementations for the RadialDistance, Douglas-Peucker, and Visvalingam-Whyatt algorithms for simplifying geometries (specifically for polygons and lines).
multipoly_suite = BenchmarkGroup(["MultiPolygon", "title:Multipolygon simplify", "subtitle:USA multipolygon"])
+
+for frac in exp10.(LinRange(log10(0.3), log10(1), 6)) # TODO: this example isn't the best. How can we get this better?
+ geom = GO.simplify(usa_multipoly; ratio = frac)
+ geom_lg, geom_go = lg_and_go(geom)
+ _tol = 0.001
+ multipoly_suite["GO-DP"][GI.npoint(geom)] = @be GO.simplify($geom_go; tol = $_tol) seconds=1
+ # multipoly_suite["GO-VW"][GI.npoint(geom)] = @be GO.simplify($(GO.VisvalingamWhyatt(; tol = $_tol)), $geom_go) seconds=1
+ multipoly_suite["GO-RD"][GI.npoint(geom)] = @be GO.simplify($(GO.RadialDistance(; tol = _tol)), $geom_go) seconds=1
+ multipoly_suite["LibGEOS"][GI.npoint(geom)] = @be LG.simplify($geom_lg, $_tol) seconds=1
+ println("""
+ For $(GI.npoint(geom)) points, the algorithms generated polygons with the following number of vertices:
+ GO-DP : $(GI.npoint( GO.simplify(geom_go; tol = _tol)))
+ GO-RD : $(GI.npoint( GO.simplify((GO.RadialDistance(; tol = _tol)), geom_go)))
+ LGeos : $(GI.npoint( LG.simplify(geom_lg, _tol)))
+ """)
+ # GO-VW : $(GI.npoint( GO.simplify((GO.VisvalingamWhyatt(; tol = _tol)), geom_go)))
+ println()
+end
+plot_trials(multipoly_suite)
julia
export simplify, VisvalingamWhyatt, DouglasPeucker, RadialDistance
+
+const _SIMPLIFY_TARGET = TraitTarget{Union{GI.PolygonTrait, GI.AbstractCurveTrait, GI.MultiPointTrait, GI.PointTrait}}()
+const MIN_POINTS = 3
+const SIMPLIFY_ALG_KEYWORDS = """
+# Keywords
+
+- \`ratio\`: the fraction of points that should remain after \`simplify\`.
+ Useful as it will generalise for large collections of objects.
+- \`number\`: the number of points that should remain after \`simplify\`.
+ Less useful for large collections of mixed size objects.
+"""
+const DOUGLAS_PEUCKER_KEYWORDS = """
+$SIMPLIFY_ALG_KEYWORDS
+- \`tol\`: the minimum distance a point will be from the line
+ joining its neighboring points.
+"""
+
+"""
+ abstract type SimplifyAlg
+
+Abstract type for simplification algorithms.
+
+# API
+
+For now, the algorithm must hold the \`number\`, \`ratio\` and \`tol\` properties.
+
+Simplification algorithm types can hook into the interface by implementing
+the \`_simplify(trait, alg, geom)\` methods for whichever traits are necessary.
+"""
+abstract type SimplifyAlg end
+
+"""
+ simplify(obj; kw...)
+ simplify(::SimplifyAlg, obj; kw...)
+
+Simplify a geometry, feature, feature collection,
+or nested vectors or a table of these.
+
+\`RadialDistance\`, \`DouglasPeucker\`, or
+\`VisvalingamWhyatt\` algorithms are available,
+listed in order of increasing quality but decreaseing performance.
+
+\`PoinTrait\` and \`MultiPointTrait\` are returned unchanged.
+
+The default behaviour is \`simplify(DouglasPeucker(; kw...), obj)\`.
+Pass in other \`SimplifyAlg\` to use other algorithms.
Keywords
julia
- \`prefilter_alg\`: \`SimplifyAlg\` algorithm used to pre-filter object before
+ using primary filtering algorithm.
+$APPLY_KEYWORDS
+
+
+Keywords for DouglasPeucker are allowed when no algorithm is specified:
+
+$DOUGLAS_PEUCKER_KEYWORDS
"""
+ RadialDistance <: SimplifyAlg
+
+Simplifies geometries by removing points less than
+\`tol\` distance from the line between its neighboring points.
+
+$SIMPLIFY_ALG_KEYWORDS
+- \`tol\`: the minimum distance between points.
+
+Note: user input \`tol\` is squared to avoid uneccesary computation in algorithm.
+"""
+@kwdef struct RadialDistance <: SimplifyAlg
+ number::Union{Int64,Nothing} = nothing
+ ratio::Union{Float64,Nothing} = nothing
+ tol::Union{Float64,Nothing} = nothing
+
+ function RadialDistance(number, ratio, tol)
+ _checkargs(number, ratio, tol)
square tolerance for reduced computation
julia
tol = isnothing(tol) ? tol : tol^2
+ new(number, ratio, tol)
+ end
+end
+
+function _simplify(alg::RadialDistance, points::Vector, _)
+ previous = first(points)
+ distances = Array{Float64}(undef, length(points))
+ for i in eachindex(points)
+ point = points[i]
+ distances[i] = _squared_euclid_distance(Float64, point, previous)
+ previous = point
+ end
+ # Never remove the end points
+ distances[begin] = distances[end] = Inf
+ return _get_points(alg, points, distances)
+end
Loop through points until stopping criteria are fulfilled
julia
i = 2 # already have first and last point added
+ start_idx, end_idx = 1, npoints
+ max_idx, max_dist = _find_max_squared_dist(points, start_idx, end_idx)
+ while i ≤ min(MIN_POINTS + 1, max_points) || (i < max_points && max_dist > max_tol)
Add next point to results
julia
i += 1
+ results[i] = max_idx
Determine which point to add next by checking left and right of point
queue_dist, queue_idx = !isempty(queue) ?
+ findmax(x -> x[4], queue) : (zero(Float64), 0)
+ elseif left_dist > right_dist # use left value as next value to add to results
+ push!(queue, right_vals) # add right value to queue
+ len_queue += 1
+ if right_dist > queue_dist
+ queue_dist = right_dist
+ queue_idx = len_queue
+ end
+ start_idx, max_idx, end_idx, max_dist = left_vals
+ else # use right value as next value to add to results
+ push!(queue, left_vals) # add left value to queue
+ len_queue += 1
+ if left_dist > queue_dist
+ queue_dist = left_dist
+ queue_idx = len_queue
+ end
+ start_idx, max_idx, end_idx, max_dist = right_vals
+ end
+ end
+ sorted_results = sort!(@view results[1:i])
+ if !preserve_endpoint && i > 3
Check start/endpoint distance to other points to see if it meets criteria
if endpt_dist < max_tol
+ results[i] = results[2]
+ sorted_results = @view results[2:i]
+ end
+ else
Remove start point and add point with maximum distance still remaining
julia
if endpt_dist < max_dist
+ insert!(results, searchsortedfirst(sorted_results, max_idx), max_idx)
+ results[i+1] = results[2]
+ sorted_results = @view results[2:i+1]
+ end
+ end
+ end
+ return points[sorted_results]
+end
+
+#= find maximum distance of any point between the start_idx and end_idx to the line formed
+by conencting the points at start_idx and end_idx. Note that the first index of maximum
+value will be used, which might cause differences in results from other algorithms.=#
+function _find_max_squared_dist(points, start_idx, end_idx)
+ max_idx = start_idx
+ max_dist = zero(Float64)
+ for i in (start_idx + 1):(end_idx - 1)
+ d = _squared_distance_line(Float64, points[i], points[start_idx], points[end_idx])
+ if d > max_dist
+ max_dist = d
+ max_idx = i
+ end
+ end
+ return max_idx, max_dist
+end
"""
+ VisvalingamWhyatt <: SimplifyAlg
+
+ VisvalingamWhyatt(; kw...)
+
+Simplifies geometries by removing points below \`tol\`
+distance from the line between its neighboring points.
+
+$SIMPLIFY_ALG_KEYWORDS
+- \`tol\`: the minimum area of a triangle made with a point and
+ its neighboring points.
+Note: user input \`tol\` is doubled to avoid uneccesary computation in algorithm.
+"""
+@kwdef struct VisvalingamWhyatt <: SimplifyAlg
+ number::Union{Int,Nothing} = nothing
+ ratio::Union{Float64,Nothing} = nothing
+ tol::Union{Float64,Nothing} = nothing
+
+ function VisvalingamWhyatt(number, ratio, tol)
+ _checkargs(number, ratio, tol)
double tolerance for reduced computation
julia
tol = isnothing(tol) ? tol : tol*2
+ return new(number, ratio, tol)
+ end
+end
+
+function _simplify(alg::VisvalingamWhyatt, points::Vector, _)
+ length(points) <= MIN_POINTS && return points
+ areas = _build_tolerances(_triangle_double_area, points)
+ return _get_points(alg, points, areas)
+end
Calculates double the area of a triangle given its vertices
function _build_tolerances(f, points)
+ nmax = length(points)
+ real_tolerances = _flat_tolerances(f, points)
+
+ tolerances = copy(real_tolerances)
+ i = [n for n in 1:nmax]
+
+ this_tolerance, min_vert = findmin(tolerances)
+ _remove!(tolerances, min_vert)
+ deleteat!(i, min_vert)
+
+ while this_tolerance < Inf
+ skip = false
+
+ if min_vert < length(i)
+ right_tolerance = f(
+ points[i[min_vert - 1]],
+ points[i[min_vert]],
+ points[i[min_vert + 1]],
+ )
+ if right_tolerance <= this_tolerance
+ right_tolerance = this_tolerance
+ skip = min_vert == 1
+ end
+
+ real_tolerances[i[min_vert]] = right_tolerance
+ tolerances[min_vert] = right_tolerance
+ end
+
+ if min_vert > 2
+ left_tolerance = f(
+ points[i[min_vert - 2]],
+ points[i[min_vert - 1]],
+ points[i[min_vert]],
+ )
+ if left_tolerance <= this_tolerance
+ left_tolerance = this_tolerance
+ skip = min_vert == 2
+ end
+ real_tolerances[i[min_vert - 1]] = left_tolerance
+ tolerances[min_vert - 1] = left_tolerance
+ end
+
+ if !skip
+ min_vert = argmin(tolerances)
+ end
+ deleteat!(i, min_vert)
+ this_tolerance = tolerances[min_vert]
+ _remove!(tolerances, min_vert)
+ end
+
+ return real_tolerances
+end
+
+function tuple_points(geom)
+ points = Array{Tuple{Float64,Float64}}(undef, GI.npoint(geom))
+ for (i, p) in enumerate(GI.getpoint(geom))
+ points[i] = (GI.x(p), GI.y(p))
+ end
+ return points
+end
+
+function _get_points(alg, points, tolerances)
+ # This assumes that \`alg\` has the properties
+ # \`tol\`, \`number\`, and \`ratio\` available...
+ tol = alg.tol
+ number = alg.number
+ ratio = alg.ratio
+ bit_indices = if !isnothing(tol)
+ _tol_indices(alg.tol::Float64, points, tolerances)
+ elseif !isnothing(number)
+ _number_indices(alg.number::Int64, points, tolerances)
+ else
+ _ratio_indices(alg.ratio::Float64, points, tolerances)
+ end
+ return points[bit_indices]
+end
+
+function _tol_indices(tol, points, tolerances)
+ tolerances .>= tol
+end
+
+function _number_indices(n, points, tolerances)
+ tol = partialsort(tolerances, length(points) - n + 1)
+ bit_indices = _tol_indices(tol, points, tolerances)
+ nselected = sum(bit_indices)
+ # If there are multiple values exactly at \`tol\` we will get
+ # the wrong output length. So we need to remove some.
+ while nselected > n
+ min_tol = Inf
+ min_i = 0
+ for i in eachindex(bit_indices)
+ bit_indices[i] || continue
+ if tolerances[i] < min_tol
+ min_tol = tolerances[i]
+ min_i = i
+ end
+ end
+ nselected -= 1
+ bit_indices[min_i] = false
+ end
+ return bit_indices
+end
+
+function _ratio_indices(r, points, tolerances)
+ n = max(3, round(Int, r * length(points)))
+ return _number_indices(n, points, tolerances)
+end
+
+function _flat_tolerances(f, points)::Vector{Float64}
+ result = Vector{Float64}(undef, length(points))
+ result[1] = result[end] = Inf
+
+ for i in 2:length(result) - 1
+ result[i] = f(points[i-1], points[i], points[i+1])
+ end
+ return result
+end
+
+function _remove!(s, i)
+ for j in i:lastindex(s)-1
+ s[j] = s[j+1]
+ end
+end
Check SimplifyAlgs inputs to make sure they are valid for below algorithms
julia
function _checkargs(number, ratio, tol)
+ count(isnothing, (number, ratio, tol)) == 2 ||
+ error("Must provide one of \`number\`, \`ratio\` or \`tol\` keywords")
+ if !isnothing(number)
+ if number < MIN_POINTS
+ error("\`number\` must be $MIN_POINTS or larger. Got $number")
+ end
+ elseif !isnothing(ratio)
+ if ratio <= 0 || ratio > 1
+ error("\`ratio\` must be 0 < ratio <= 1. Got $ratio")
+ end
+ else # !isnothing(tol)
+ if tol ≤ 0
+ error("\`tol\` must be a positive number. Got $tol")
+ end
+ end
+ return nothing
+end
`,70),E=[e];function r(d,g,y,F,o,c){return a(),i("div",null,E)}const D=s(p,[["render",r]]);export{u as __pageData,D as default};
diff --git a/previews/PR149/assets/source_transformations_simplify.md.ChtGmeP2.lean.js b/previews/PR149/assets/source_transformations_simplify.md.ChtGmeP2.lean.js
new file mode 100644
index 000000000..39736bd58
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_simplify.md.ChtGmeP2.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const h="/GeometryOps.jl/previews/PR149/assets/mvimxvw.Bglvb-jp.png",l="/GeometryOps.jl/previews/PR149/assets/cbtnibw.B94PsR1K.png",k="/GeometryOps.jl/previews/PR149/assets/eouzjij.CXk0JbJI.png",t="/GeometryOps.jl/previews/PR149/assets/awkfodg.CIBNG3Jj.png",u=JSON.parse('{"title":"Geometry simplification","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/simplify.md","filePath":"source/transformations/simplify.md","lastUpdated":null}'),p={name:"source/transformations/simplify.md"},e=n("",70),E=[e];function r(d,g,y,F,o,c){return a(),i("div",null,E)}const D=s(p,[["render",r]]);export{u as __pageData,D as default};
diff --git a/previews/PR149/assets/source_transformations_transform.md.div83wbv.js b/previews/PR149/assets/source_transformations_transform.md.div83wbv.js
new file mode 100644
index 000000000..44c267432
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_transform.md.div83wbv.js
@@ -0,0 +1,55 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const d=JSON.parse('{"title":"Pointwise transformation","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/transform.md","filePath":"source/transformations/transform.md","lastUpdated":null}'),t={name:"source/transformations/transform.md"},l=n(`
`,4),e=[l];function p(h,r,k,o,g,F){return a(),i("div",null,e)}const y=s(t,[["render",p]]);export{d as __pageData,y as default};
diff --git a/previews/PR149/assets/source_transformations_transform.md.div83wbv.lean.js b/previews/PR149/assets/source_transformations_transform.md.div83wbv.lean.js
new file mode 100644
index 000000000..99228be8b
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_transform.md.div83wbv.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const d=JSON.parse('{"title":"Pointwise transformation","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/transform.md","filePath":"source/transformations/transform.md","lastUpdated":null}'),t={name:"source/transformations/transform.md"},l=n("",4),e=[l];function p(h,r,k,o,g,F){return a(),i("div",null,e)}const y=s(t,[["render",p]]);export{d as __pageData,y as default};
diff --git a/previews/PR149/assets/source_transformations_tuples.md.BRc6CjCN.js b/previews/PR149/assets/source_transformations_tuples.md.BRc6CjCN.js
new file mode 100644
index 000000000..b9ee30be1
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_tuples.md.BRc6CjCN.js
@@ -0,0 +1,19 @@
+import{_ as s,c as a,o as n,a6 as i}from"./chunks/framework.CDOaXZPW.js";const u=JSON.parse('{"title":"Tuple conversion","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/tuples.md","filePath":"source/transformations/tuples.md","lastUpdated":null}'),e={name:"source/transformations/tuples.md"},t=i(`
"""
+ tuples(obj)
+
+Convert all points in \`obj\` to \`Tuple\`s, wherever the are nested.
+
+Returns a similar object or collection of objects using GeoInterface.jl
+geometries wrapping \`Tuple\` points.
Keywords
julia
$APPLY_KEYWORDS
+"""
+function tuples(geom, ::Type{T} = Float64; kw...) where T
+ if _is3d(geom)
+ return apply(PointTrait(), geom; kw...) do p
+ (T(GI.x(p)), T(GI.y(p)), T(GI.z(p)))
+ end
+ else
+ return apply(PointTrait(), geom; kw...) do p
+ (T(GI.x(p)), T(GI.y(p)))
+ end
+ end
+end
`,6),p=[t];function l(o,r,h,c,k,d){return n(),a("div",null,p)}const g=s(e,[["render",l]]);export{u as __pageData,g as default};
diff --git a/previews/PR149/assets/source_transformations_tuples.md.BRc6CjCN.lean.js b/previews/PR149/assets/source_transformations_tuples.md.BRc6CjCN.lean.js
new file mode 100644
index 000000000..9a7b015e6
--- /dev/null
+++ b/previews/PR149/assets/source_transformations_tuples.md.BRc6CjCN.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as a,o as n,a6 as i}from"./chunks/framework.CDOaXZPW.js";const u=JSON.parse('{"title":"Tuple conversion","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/tuples.md","filePath":"source/transformations/tuples.md","lastUpdated":null}'),e={name:"source/transformations/tuples.md"},t=i("",6),p=[t];function l(o,r,h,c,k,d){return n(),a("div",null,p)}const g=s(e,[["render",l]]);export{u as __pageData,g as default};
diff --git a/previews/PR149/assets/source_utils.md.qql9obpk.js b/previews/PR149/assets/source_utils.md.qql9obpk.js
new file mode 100644
index 000000000..1f08d80f7
--- /dev/null
+++ b/previews/PR149/assets/source_utils.md.qql9obpk.js
@@ -0,0 +1,120 @@
+import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.CDOaXZPW.js";const y=JSON.parse('{"title":"Utility functions","description":"","frontmatter":{},"headers":[],"relativePath":"source/utils.md","filePath":"source/utils.md","lastUpdated":null}'),t={name:"source/utils.md"},p=n(`
Spatial joins can be done between any geometry types (from geometrycollections to points), just as geometrical predicates can be evaluated on any geometries.
In this tutorial, we will show how to perform a spatial join on first a toy dataset and then two Natural Earth datasets, to show how this can be used in the real world.
In order to perform the spatial join, we use FlexiJoins.jl to perform the join, specifically using its by_pred joining method. This allows the user to specify a predicate in the following manner:
julia
[inner/left/right/outer/...]join((table1, table1),
+ by_pred(:table1_column, predicate_function, :table2_column) # & add other conditions here
+)
We have enabled the use of all of GeometryOps' boolean comparisons here. These are:
This example demonstrates how to perform a spatial join between two datasets: a set of polygons and a set of randomly generated points.
The polygons are represented as a DataFrame with geometries and colors, while the points are stored in a separate DataFrame.
The spatial join is performed using the contains predicate from GeometryOps, which checks if each point is contained within any of the polygons. The resulting joined DataFrame is then used to plot the points, colored according to the containing polygon.
First, we generate our data. We create two triangle polygons which, together, span the rectangle (0, 0, 1, 1), and a set of points which are randomly distributed within this rectangle.
julia
import GeoInterface as GI, GeometryOps as GO
+using FlexiJoins, DataFrames
+
+using CairoMakie, GeoInterfaceMakie
+
+pl = GI.Polygon([GI.LinearRing([(0, 0), (1, 0), (1, 1), (0, 0)])])
+pu = GI.Polygon([GI.LinearRing([(0, 0), (0, 1), (1, 1), (0, 0)])])
+poly_df = DataFrame(geometry = [pl, pu], color = [:red, :blue])
+f, a, p = poly(poly_df.geometry; color = tuple.(poly_df.color, 0.3))
Here, the upper polygon is blue, and the lower polygon is red. Keep this in mind!
Suppose I have a list of polygons representing administrative regions (or mining sites, or what have you), and I have a list of polygons for each country. I want to find the country each region is in.
julia
import GeoInterface as GI, GeometryOps as GO
+using FlexiJoins, DataFrames, GADM # GADM gives us country and sublevel geometry
+
+using CairoMakie, GeoInterfaceMakie
+
+country_df = GADM.get.(["JPN", "USA", "IND", "DEU", "FRA"]) |> DataFrame
+country_df.geometry = GI.GeometryCollection.(GO.tuples.(country_df.geom))
+
+state_doublets = [
+ ("USA", "New York"),
+ ("USA", "California"),
+ ("IND", "Karnataka"),
+ ("DEU", "Berlin"),
+ ("FRA", "Grand Est"),
+ ("JPN", "Tokyo"),
+]
+
+state_full_df = (x -> GADM.get(x...)).(state_doublets) |> DataFrame
+state_full_df.geom = GO.tuples.(only.(state_full_df.geom))
+state_compact_df = state_full_df[:, [:geom, :NAME_1]]
This is how you would do this, but it doesn't work yet, since the GeometryOps predicates are quite slow on large polygons. If you try this, the code will continue to run for a very, very long time (it took 12 hours on my laptop, but with minimal CPU usage).
This will enable FlexiJoins to support your custom function, when it's passed to by_pred(:geometry, my_predicate_function, :geometry).
`,37);function T(_,b,f,D,Q,w){return t(),a("div",null,[r,s("p",null,[i("Spatial joins are "),E,i(" which are based not on equality, but on some predicate "),s("mjx-container",d,[(t(),a("svg",o,y)),c]),i(", which takes two geometries, and returns a value of either "),F,i(" or "),u,i(". For geometries, the "),m,i(" spatial relationship model is used to determine the spatial relationship between two geometries.")]),C])}const v=h(k,[["render",T]]);export{B as __pageData,v as default};
diff --git a/previews/PR149/assets/tutorials_spatial_joins.md.jQ7F_JVS.lean.js b/previews/PR149/assets/tutorials_spatial_joins.md.jQ7F_JVS.lean.js
new file mode 100644
index 000000000..7caaafd50
--- /dev/null
+++ b/previews/PR149/assets/tutorials_spatial_joins.md.jQ7F_JVS.lean.js
@@ -0,0 +1 @@
+import{_ as h,c as a,j as s,a as i,a6 as n,o as t}from"./chunks/framework.CDOaXZPW.js";const e="/GeometryOps.jl/previews/PR149/assets/ofkrynl.3UVIT8DR.png",l="/GeometryOps.jl/previews/PR149/assets/poawckn.D1sul6_F.png",p="/GeometryOps.jl/previews/PR149/assets/ptvygff.DQj6s62y.png",B=JSON.parse('{"title":"Spatial joins","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/spatial_joins.md","filePath":"tutorials/spatial_joins.md","lastUpdated":null}'),k={name:"tutorials/spatial_joins.md"},r=s("h1",{id:"Spatial-joins",tabindex:"-1"},[i("Spatial joins "),s("a",{class:"header-anchor",href:"#Spatial-joins","aria-label":'Permalink to "Spatial joins {#Spatial-joins}"'},"")],-1),E=s("a",{href:"https://www.geeksforgeeks.org/sql-join-set-1-inner-left-right-and-full-joins/",target:"_blank",rel:"noreferrer"},"table joins",-1),d={class:"MathJax",jax:"SVG",style:{direction:"ltr",position:"relative"}},o={style:{overflow:"visible","min-height":"1px","min-width":"1px","vertical-align":"-0.566ex"},xmlns:"http://www.w3.org/2000/svg",width:"6.307ex",height:"2.262ex",role:"img",focusable:"false",viewBox:"0 -750 2787.7 1000","aria-hidden":"true"},g=n("",1),y=[g],c=s("mjx-assistive-mml",{unselectable:"on",display:"inline",style:{top:"0px",left:"0px",clip:"rect(1px, 1px, 1px, 1px)","-webkit-touch-callout":"none","-webkit-user-select":"none","-khtml-user-select":"none","-moz-user-select":"none","-ms-user-select":"none","user-select":"none",position:"absolute",padding:"1px 0px 0px 0px",border:"0px",display:"block",width:"auto",overflow:"hidden"}},[s("math",{xmlns:"http://www.w3.org/1998/Math/MathML"},[s("mi",null,"p"),s("mo",{stretchy:"false"},"("),s("mi",null,"x"),s("mo",null,","),s("mi",null,"y"),s("mo",{stretchy:"false"},")")])],-1),F=s("code",null,"true",-1),u=s("code",null,"false",-1),m=s("a",{href:"https://en.wikipedia.org/wiki/DE-9IM",target:"_blank",rel:"noreferrer"},[s("code",null,"DE-9IM")],-1),C=n("",37);function T(_,b,f,D,Q,w){return t(),a("div",null,[r,s("p",null,[i("Spatial joins are "),E,i(" which are based not on equality, but on some predicate "),s("mjx-container",d,[(t(),a("svg",o,y)),c]),i(", which takes two geometries, and returns a value of either "),F,i(" or "),u,i(". For geometries, the "),m,i(" spatial relationship model is used to determine the spatial relationship between two geometries.")]),C])}const v=h(k,[["render",T]]);export{B as __pageData,v as default};
diff --git a/previews/PR149/assets/xsucobl.CULn5saZ.png b/previews/PR149/assets/xsucobl.CULn5saZ.png
new file mode 100644
index 000000000..c834125d6
Binary files /dev/null and b/previews/PR149/assets/xsucobl.CULn5saZ.png differ
diff --git a/previews/PR149/assets/znyubcg.-VpeHhXX.png b/previews/PR149/assets/znyubcg.-VpeHhXX.png
new file mode 100644
index 000000000..bc1c05436
Binary files /dev/null and b/previews/PR149/assets/znyubcg.-VpeHhXX.png differ
diff --git a/previews/PR149/call_notes.html b/previews/PR149/call_notes.html
new file mode 100644
index 000000000..4c3b7f79e
--- /dev/null
+++ b/previews/PR149/call_notes.html
@@ -0,0 +1,25 @@
+
+
+
+
+
+ GeometryOps.jl
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GeometryOps.jl is a package for geometric calculations on (primarily 2D) geometries.
The driving idea behind this package is to unify all the disparate packages for geometric calculations in Julia, and make them GeoInterface.jl-compatible. We seem to be focusing primarily on 2/2.5D geometries for now.
Most of the usecases are driven by GIS and similar Earth data workflows, so this might be a bit specialized towards that, but methods should always be general to any coordinate space.
We welcome contributions, either as pull requests or discussion on issues!
+
+
+
+
\ No newline at end of file
diff --git a/previews/PR149/introduction.html b/previews/PR149/introduction.html
new file mode 100644
index 000000000..2e4487511
--- /dev/null
+++ b/previews/PR149/introduction.html
@@ -0,0 +1,25 @@
+
+
+
+
+
+ Introduction | GeometryOps.jl
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GeometryOps.jl is a package for geometric calculations on (primarily 2D) geometries.
The driving idea behind this package is to unify all the disparate packages for geometric calculations in Julia, and make them GeoInterface.jl-compatible. We seem to be focusing primarily on 2/2.5D geometries for now.
Most of the usecases are driven by GIS and similar Earth data workflows, so this might be a bit specialized towards that, but methods should always be general to any coordinate space.
We welcome contributions, either as pull requests or discussion on issues!
GeometryOps exposes functions like apply and applyreduce, as well as the fix and prepare APIs, that represent paradigms of programming, by which we mean the ability to program in a certain way, and in so doing, fit neatly into the tools we've built without needing to re-implement the wheel.
Below, we'll describe some of the foundational paradigms of GeometryOps, and why you should care!
The apply function allows you to decompose a given collection of geometries down to a certain level, operate on it, and reconstruct it back to the same nested form as the original. In general, its invocation is:
julia
apply(f, trait::Trait, geom)
Functionally, it's similar to map in the way you apply it to geometries - except that you tell it at which level it should stop, by passing a trait to it.
apply will start by decomposing the geometry, feature, featurecollection, iterable, or table that you pass to it, and stop when it encounters a geometry for which GI.trait(geom) isa Trait. This encompasses unions of traits especially, but beware that any geometry which is not explicitly handled, and hits GI.PointTrait, will cause an error.
apply is unlike map in that it returns reconstructed geometries, instead of the raw output of the function. If you want a purely map-like behaviour, like calculating the length of each linestring in your feature collection, then call GO.flatten(f, trait, geom), which will decompose each geometry to the given trait and apply f to it, returning the decomposition as a flattened vector.
applyreduce is like the previous map-based approach that we mentioned, except that it reduces the result of f by op. Note that applyreduce does not guarantee associativity, so it's best to have typeof(init) == returntype(op).
The fix and prepare paradigms are different from apply, though they are built on top of it. They involve the use of structs as "actions", where a constructed object indicates an action that should be taken. A trait like interface prescribes the level (polygon, linestring, point, etc) at which each action should be applied.
In general, the idea here is to be able to invoke several actions efficiently and simultaneously, for example when correcting invalid geometries, or instantiating a Prepared geometry with several preparations (sorted edge lists, rtrees, monotone chains, etc.)
+
+
+
+
\ No newline at end of file
diff --git a/previews/PR149/peculiarities.html b/previews/PR149/peculiarities.html
new file mode 100644
index 000000000..8e0b50cbc
--- /dev/null
+++ b/previews/PR149/peculiarities.html
@@ -0,0 +1,25 @@
+
+
+
+
+
+ Peculiarities | GeometryOps.jl
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
apply returns the target geometries returned by f, whatever type/package they are from, but geometries, features or feature collections that wrapped the target are replaced with GeoInterace.jl wrappers with matching GeoInterface.trait to the originals. All non-geointerface iterables become Arrays. Tables.jl compatible tables are converted either back to the original type if a Tables.materializer is defined, and if not then returned as generic NamedTuple column tables (i.e., a NamedTuple of vectors).
It is recommended for consistency that f returns GeoInterface geometries unless there is a performance/conversion overhead to doing that.
Why do you want me to provide a target in set operations?
In polygon set operations like intersection, difference, and union, many different geometry types may be obtained - depending on the relationship between the polygons. For example, when performing an union on two nonintersecting polygons, one would technically have two disjoint polygons as an output.
We use the target keyword to allow the user to control which kinds of geometry they want back. For example, setting target to PolygonTrait will cause a vector of polygons to be returned (this is the only currently supported behaviour). In future, we may implement MultiPolygonTrait or GeometryCollectionTrait targets which will return a single geometry, as LibGEOS and ArchGDAL do.
This also allows for a lot more type stability - when you ask for polygons, we won't return a geometrycollection with line segments. Especially in simulation workflows, this is excellent for simplified data processing.
These are internals and explicitly not public API, meaning they may change at any time!
When dispatch can be controlled by the value of a boolean variable, this introduces type instability. Instead of introducing type instability, we chose to encode our boolean decision variables, like threaded and calc_extent in apply, as types. This allows the compiler to reason about what will happen, and call the correct compiled method, in a stable way without worrying about
+
+
+
+
\ No newline at end of file
diff --git a/previews/PR149/siteinfo.js b/previews/PR149/siteinfo.js
new file mode 100644
index 000000000..3dbf091f5
--- /dev/null
+++ b/previews/PR149/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR149";
diff --git a/previews/PR149/source/GeometryOps.html b/previews/PR149/source/GeometryOps.html
new file mode 100644
index 000000000..53ace8e88
--- /dev/null
+++ b/previews/PR149/source/GeometryOps.html
@@ -0,0 +1,92 @@
+
+
+
+
+
+ GeometryOps.jl
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Import all names from GeoInterface and Extents, so users can do GO.extent or GO.trait.
julia
for name in names(GeoInterface)
+ @eval using GeoInterface: $name
+end
+for name in names(Extents)
+ @eval using GeoInterface.Extents: $name
+end
+
+function __init__()
This is the GeoInterface-compatible implementation. First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
julia
const _ANGLE_TARGETS = TraitTarget{Union{GI.PolygonTrait,GI.AbstractCurveTrait,GI.MultiPointTrait,GI.PointTrait}}()
+
+"""
+ angles(geom, ::Type{T} = Float64)
+
+Returns the angles of a geometry or collection of geometries.
+This is computed differently for different geometries:
+
+ - The angles of a point is an empty vector.
+ - The angles of a single line segment is an empty vector.
+ - The angles of a linestring or linearring is a vector of angles formed by the curve.
+ - The angles of a polygin is a vector of vectors of angles formed by each ring.
+ - The angles of a multi-geometry collection is a vector of the angles of each of the
+ sub-geometries as defined above.
+
+Result will be a Vector, or nested set of vectors, of type T where an optional argument with
+a default value of Float64.
+"""
+function angles(geom, ::Type{T} = Float64; threaded =false) where T <: AbstractFloat
+ applyreduce(vcat, _ANGLE_TARGETS, geom; threaded, init = Vector{T}()) do g
+ _angles(T, GI.trait(g), g)
+ end
+end
Points and single line segments have no angles
julia
_angles(::Type{T}, ::Union{GI.PointTrait, GI.MultiPointTrait, GI.LineTrait}, geom) where T = T[]
+
+#= The angles of a linestring are the angles formed by the line. If the first and last point
+are not explicitly repeated, the geom is not considered closed. The angles should all be on
+one side of the line, but a particular side is not guaranteed by this function. =#
+function _angles(::Type{T}, ::GI.LineStringTrait, geom) where T
+ npoints = GI.npoint(geom)
+ first_last_equal = equals(GI.getpoint(geom, 1), GI.getpoint(geom, npoints))
+ angle_list = Vector{T}(undef, npoints - (first_last_equal ? 1 : 2))
+ _find_angles!(
+ T, angle_list, geom;
+ offset = first_last_equal, close_geom = false,
+ )
+ return angle_list
+end
+
+#= The angles of a linearring are the angles within the closed line and include the angles
+formed by connecting the first and last points of the curve. =#
+function _angles(::Type{T}, ::GI.LinearRingTrait, geom; interior = true) where T
+ npoints = GI.npoint(geom)
+ first_last_equal = equals(GI.getpoint(geom, 1), GI.getpoint(geom, npoints))
+ angle_list = Vector{T}(undef, npoints - (first_last_equal ? 1 : 0))
+ _find_angles!(
+ T, angle_list, geom;
+ offset = true, close_geom = !first_last_equal, interior = interior,
+ )
+ return angle_list
+end
+
+#= The angles of a polygon is a vector of polygon angles. Note that if there are holes
+within the polyogn, the angles will be listed after the exterior ring angles in order of the
+holes. All angles, including the hole angles, are interior angles of the polygon.=#
+function _angles(::Type{T}, ::GI.PolygonTrait, geom) where T
+ angles = _angles(T, GI.LinearRingTrait(), GI.getexterior(geom); interior = true)
+ for h in GI.gethole(geom)
+ append!(angles, _angles(T, GI.LinearRingTrait(), h; interior = false))
+ end
+ return angles
+end
Find angles of a curve and insert the values into the angle_list. If offset is true, then save space for the angle at the first vertex, as the curve is closed, at the front of angle_list. If close_geom is true, then despite the first and last point not being explicitly repeated, the curve is closed and the angle of the last point should be added to angle_list. If interior is true, then all angles will be on the same side of the line
julia
function _find_angles!(
+ ::Type{T}, angle_list, geom;
+ offset, close_geom, interior = true,
+) where T
+ local p1, prev_p1_diff, p2_p1_diff
+ local start_point, start_diff
+ local extreem_idx, extreem_x, extreem_y
+ i_offset = offset ? 1 : 0
Loop through the curve and find each of the angels
julia
for (i, p2) in enumerate(GI.getpoint(geom))
+ xp2, yp2 = GI.x(p2), GI.y(p2)
+ #= Find point with smallest x values (and smallest y in case of a tie) as this point
+ is know to be convex. =#
+ if i == 1 || (xp2 < extreem_x || (xp2 == extreem_x && yp2 < extreem_y))
+ extreem_idx = i
+ extreem_x, extreem_y = xp2, yp2
+ end
+ if i > 1
+ p2_p1_diff = (xp2 - GI.x(p1), yp2 - GI.y(p1))
+ if i == 2
+ start_point = p1
+ start_diff = p2_p1_diff
+ else
+ angle_list[i - 2 + i_offset] = _diffs_calc_angle(T, prev_p1_diff, p2_p1_diff)
+ end
+ prev_p1_diff = -1 .* p2_p1_diff
+ end
+ p1 = p2
+ end
If the last point of geometry should be the same as the first, calculate closing angle
If needed, calculate first angle corresponding to the first point
julia
if offset
+ angle_list[1] = _diffs_calc_angle(T, prev_p1_diff, start_diff)
+ end
+ #= Make sure that all of the angles are on the same side of the line and inside of the
+ closed ring if the input geometry is closed. =#
+ inside_sgn = sign(angle_list[extreem_idx]) * (interior ? 1 : -1)
+ for i in eachindex(angle_list)
+ idx_sgn = sign(angle_list[i])
+ if idx_sgn == -1
+ angle_list[i] = abs(angle_list[i])
+ end
+ if idx_sgn != inside_sgn
+ angle_list[i] = 360 - angle_list[i]
+ end
+ end
+ return
+end
Calculate the angle between two vectors defined by the previous and current Δx and Δys. Angle will have a sign corresponding to the sign of the cross product between the two vectors. All angles of one sign in a given geometry are convex, while those of the other sign are concave. However, the sign corresponding to each of these can vary based on geometry and thus you must compare to an angle that is know to be convex or concave.
Area is the amount of space occupied by a two-dimensional figure. It is always a positive value. Signed area is simply the integral over the exterior path of a polygon, minus the sum of integrals over its interior holes. It is signed such that a clockwise path has a positive area, and a counterclockwise path has a negative area. The area is the absolute value of the signed area.
To provide an example, consider this rectangle:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+rect = GI.Polygon([[(0,0), (0,1), (1,1), (1,0), (0, 0)]])
+f, a, p = poly(collect(GI.getpoint(rect)); axis = (; aspect = DataAspect()))
This is clearly a rectangle, etc. But now let's look at how the points look:
The points are ordered in a counterclockwise fashion, which means that the signed area is negative. If we reverse the order of the points, we get a postive area.
This is the GeoInterface-compatible implementation. First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Note that area and signed area are zero for all points and curves, even if the curves are closed like with a linear ring. Also note that signed area really only makes sense for polygons, given with a multipolygon can have several polygons each with a different orientation and thus the absolute value of the signed area might not be the area. This is why signed area is only implemented for polygons.
Targets for applys functions
julia
const _AREA_TARGETS = TraitTarget{Union{GI.PolygonTrait,GI.AbstractCurveTrait,GI.MultiPointTrait,GI.PointTrait}}()
+
+"""
+ area(geom, [T = Float64])::T
+
+Returns the area of a geometry or collection of geometries.
+This is computed slightly differently for different geometries:
+
+ - The area of a point/multipoint is always zero.
+ - The area of a curve/multicurve is always zero.
+ - The area of a polygon is the absolute value of the signed area.
+ - The area multi-polygon is the sum of the areas of all of the sub-polygons.
+ - The area of a geometry collection, feature collection of array/iterable
+ is the sum of the areas of all of the sub-geometries.
+
+Result will be of type T, where T is an optional argument with a default value
+of Float64.
+"""
+function area(geom, ::Type{T} = Float64; threaded=false) where T <: AbstractFloat
+ applyreduce(+, _AREA_TARGETS, geom; threaded, init=zero(T)) do g
+ _area(T, GI.trait(g), g)
+ end
+end
+
+"""
+ signed_area(geom, [T = Float64])::T
+
+Returns the signed area of a single geometry, based on winding order.
+This is computed slighly differently for different geometries:
+
+ - The signed area of a point is always zero.
+ - The signed area of a curve is always zero.
+ - The signed area of a polygon is computed with the shoelace formula and is
+ positive if the polygon coordinates wind clockwise and negative if
+ counterclockwise.
+ - You cannot compute the signed area of a multipolygon as it doesn't have a
+ meaning as each sub-polygon could have a different winding order.
+
+Result will be of type T, where T is an optional argument with a default value
+of Float64.
+"""
+signed_area(geom, ::Type{T} = Float64) where T <: AbstractFloat =
+ _signed_area(T, GI.trait(geom), geom)
Points, MultiPoints, Curves, MultiCurves
julia
_area(::Type{T}, ::GI.AbstractGeometryTrait, geom) where T = zero(T)
+
+_signed_area(::Type{T}, ::GI.AbstractGeometryTrait, geom) where T = zero(T)
LibGEOS treats linear rings as zero area. I disagree with that but we should probably maintain compatibility...
julia
_area(::Type{T}, tr::GI.LinearRingTrait, geom) where T = 0 # could be abs(_signed_area(T, tr, geom))
+
+_signed_area(::Type{T}, ::GI.LinearRingTrait, geom) where T = 0 # could be _signed_area(T, tr, geom)
Polygons
julia
_area(::Type{T}, trait::GI.PolygonTrait, poly) where T =
+ abs(_signed_area(T, trait, poly))
+
+function _signed_area(::Type{T}, ::GI.PolygonTrait, poly) where T
+ GI.isempty(poly) && return zero(T)
+ s_area = _signed_area(T, GI.getexterior(poly))
+ area = abs(s_area)
+ area == 0 && return area
Remove hole areas from total
julia
for hole in GI.gethole(poly)
+ area -= abs(_signed_area(T, hole))
+ end
Winding of exterior ring determines sign
julia
return area * sign(s_area)
+end
One term of the shoelace area formula
julia
_area_component(p1, p2) = GI.x(p1) * GI.y(p2) - GI.y(p1) * GI.x(p2)
+
+#= Calculates the signed area of a given curve. This is equivalent to integrating
+to find the area under the curve. Even if curve isn't explicitly closed by
+repeating the first point at the end of the coordinates, curve is still assumed
+to be closed. =#
+function _signed_area(::Type{T}, geom) where T
+ area = zero(T)
+ np = GI.npoint(geom)
+ np == 0 && return area
+
+ first = true
+ local pfirst, p1
Integrate the area under the curve
julia
for p2 in GI.getpoint(geom)
Skip the first and do it later This lets us work within one iteration over geom, which means on C call when using points from external libraries.
julia
if first
+ p1 = pfirst = p2
+ first = false
+ continue
+ end
Accumulate the area into area
julia
area += _area_component(p1, p2)
+ p1 = p2
+ end
Complete the last edge. If the first and last where the same this will be zero
Generalized barycentric coordinates are a generalization of barycentric coordinates, which are typically used in triangles, to arbitrary polygons.
They provide a way to express a point within a polygon as a weighted average of the polygon's vertices.
In the case of a triangle, barycentric coordinates are a set of three numbers , each associated with a vertex of the triangle. Any point within the triangle can be expressed as a weighted average of the vertices, where the weights are the barycentric coordinates. The weights sum to 1, and each is non-negative.
For a polygon with vertices, generalized barycentric coordinates are a set of numbers , each associated with a vertex of the polygon. Any point within the polygon can be expressed as a weighted average of the vertices, where the weights are the generalized barycentric coordinates.
As with the triangle case, the weights sum to 1, and each is non-negative.
In some cases, we actually want barycentric interpolation, and have no interest in the coordinates themselves.
However, the coordinates can be useful for debugging, and when performing 3D rendering, multiple barycentric values (depth, uv) are needed for depth buffering.
julia
const _VecTypes = Union{Tuple{Vararg{T, N}}, GeometryBasics.StaticArraysCore.StaticArray{Tuple{N}, T, 1}} where {N, T}
+
+"""
+ abstract type AbstractBarycentricCoordinateMethod
+
+Abstract supertype for barycentric coordinate methods.
+The subtypes may serve as dispatch types, or may cache
+some information about the target polygon.
+
+# API
+The following methods must be implemented for all subtypes:
+- `barycentric_coordinates!(λs::Vector{<: Real}, method::AbstractBarycentricCoordinateMethod, exterior::Vector{<: Point{2, T1}}, point::Point{2, T2})`
+- `barycentric_interpolate(method::AbstractBarycentricCoordinateMethod, exterior::Vector{<: Point{2, T1}}, values::Vector{V}, point::Point{2, T2})::V`
+- `barycentric_interpolate(method::AbstractBarycentricCoordinateMethod, exterior::Vector{<: Point{2, T1}}, interiors::Vector{<: Vector{<: Point{2, T1}}} values::Vector{V}, point::Point{2, T2})::V`
+The rest of the methods will be implemented in terms of these, and have efficient dispatches for broadcasting.
+"""
+abstract type AbstractBarycentricCoordinateMethod end
+
+Base.@propagate_inbounds function barycentric_coordinates!(λs::Vector{<: Real}, method::AbstractBarycentricCoordinateMethod, polypoints::AbstractVector{<: Point{N1, T1}}, point::Point{N2, T2}) where {N1, N2, T1 <: Real, T2 <: Real}
+ @boundscheck @assert length(λs) == length(polypoints)
+ @boundscheck @assert length(polypoints) >= 3
+
+ @error("Not implemented yet for method $(method).")
+end
+Base.@propagate_inbounds barycentric_coordinates!(λs::Vector{<: Real}, polypoints::AbstractVector{<: Point{N1, T1}}, point::Point{N2, T2}) where {N1, N2, T1 <: Real, T2 <: Real} = barycentric_coordinates!(λs, MeanValue(), polypoints, point)
This is the GeoInterface-compatible method.
julia
"""
+ barycentric_coordinates!(λs::Vector{<: Real}, method::AbstractBarycentricCoordinateMethod, polygon, point)
+
+Loads the barycentric coordinates of `point` in `polygon` into `λs` using the barycentric coordinate method `method`.
+
+`λs` must be of the length of the polygon plus its holes.
+
+!!! tip
+ Use this method to avoid excess allocations when you need to calculate barycentric coordinates for many points.
+"""
+Base.@propagate_inbounds function barycentric_coordinates!(λs::Vector{<: Real}, method::AbstractBarycentricCoordinateMethod, polygon, point)
+ @assert GeoInterface.trait(polygon) isa GeoInterface.PolygonTrait
+ @assert GeoInterface.trait(point) isa GeoInterface.PointTrait
+ passable_polygon = GeoInterface.convert(GeometryBasics, polygon)
+ @assert passable_polygon isa GeometryBasics.Polygon "The polygon was converted to a $(typeof(passable_polygon)), which is not a `GeometryBasics.Polygon`."
+ passable_point = GeoInterface.convert(GeometryBasics, point)
+ return barycentric_coordinates!(λs, method, passable_polygon, Point2(passable_point))
+end
+
+Base.@propagate_inbounds function barycentric_coordinates(method::AbstractBarycentricCoordinateMethod, polypoints::AbstractVector{<: Point{N1, T1}}, point::Point{N2, T2}) where {N1, N2, T1 <: Real, T2 <: Real}
+ λs = zeros(promote_type(T1, T2), length(polypoints))
+ barycentric_coordinates!(λs, method, polypoints, point)
+ return λs
+end
+Base.@propagate_inbounds barycentric_coordinates(polypoints::AbstractVector{<: Point{N1, T1}}, point::Point{N2, T2}) where {N1, N2, T1 <: Real, T2 <: Real} = barycentric_coordinates(MeanValue(), polypoints, point)
3D polygons are considered to have their vertices in the XY plane, and the Z coordinate must represent some value. This is to say that the Z coordinate is interpreted as an M coordinate.
This method is the one which supports GeoInterface.
julia
"""
+ barycentric_interpolate(method = MeanValue(), polygon, values::AbstractVector{V}, point)
+
+Returns the interpolated value at `point` within `polygon` using the barycentric coordinate method `method`.
+`values` are the per-point values for the polygon which are to be interpolated.
+
+Returns an object of type `V`.
+
+!!! warning
+ Barycentric interpolation is currently defined only for 2-dimensional polygons.
+ If you pass a 3-D polygon in, the Z coordinate will be used as per-vertex value to be interpolated
+ (the M coordinate in GIS parlance).
+"""
+Base.@propagate_inbounds function barycentric_interpolate(method::AbstractBarycentricCoordinateMethod, polygon, values::AbstractVector{V}, point) where V
+ @assert GeoInterface.trait(polygon) isa GeoInterface.PolygonTrait
+ @assert GeoInterface.trait(point) isa GeoInterface.PointTrait
+ passable_polygon = GeoInterface.convert(GeometryBasics, polygon)
+ @assert passable_polygon isa GeometryBasics.Polygon "The polygon was converted to a $(typeof(passable_polygon)), which is not a `GeometryBasics.Polygon`."
+ # first_poly_point = GeoInterface.getpoint(GeoInterface.getexterior(polygon))
+ passable_point = GeoInterface.convert(GeometryBasics, point)
+ return barycentric_interpolate(method, passable_polygon, Point2(passable_point))
+end
+Base.@propagate_inbounds barycentric_interpolate(polygon, values::AbstractVector{V}, point) where V = barycentric_interpolate(MeanValue(), polygon, values, point)
+
+"""
+ weighted_mean(weight::Real, x1, x2)
+
+Returns the weighted mean of `x1` and `x2`, where `weight` is the weight of `x1`.
+
+Specifically, calculates `x1 * weight + x2 * (1 - weight)`.
+
+!!! note
+ The idea for this method is that you can override this for custom types, like Color types, in extension modules.
+"""
+function weighted_mean(weight::WT, x1, x2) where {WT <: Real}
+ return muladd(x1, weight, x2 * (oneunit(WT) - weight))
+end
+
+
+"""
+ MeanValue() <: AbstractBarycentricCoordinateMethod
+
+This method calculates barycentric coordinates using the mean value method.
+
+# References
+
+"""
+struct MeanValue <: AbstractBarycentricCoordinateMethod
+end
Before we go to the actual implementation, there are some quick and simple utility functions that we need to implement. These are mainly for convenience and code brevity.
julia
"""
+ _det(s1::Point2{T1}, s2::Point2{T2}) where {T1 <: Real, T2 <: Real}
+
+Returns the determinant of the matrix formed by `hcat`'ing two points `s1` and `s2`.
+
+Specifically, this is:
+```julia
+s1[1] * s2[2] - s1[2] * s2[1]
+```
+"""
+function _det(s1::_VecTypes{2, T1}, s2::_VecTypes{2, T2}) where {T1 <: Real, T2 <: Real}
+ return s1[1] * s2[2] - s1[2] * s2[1]
+end
+
+"""
+ t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)
+
+Returns the "T-value" as described in Hormann's presentation [^HormannPresentation] on how to calculate
+the mean-value coordinate.
+
+Here, `sᵢ` is the vector from vertex `vᵢ` to the point, and `rᵢ` is the norm (length) of `sᵢ`.
+`s` must be `Point` and `r` must be real numbers.
+
+```math
+tᵢ = \\frac{\\mathrm{det}\\left(sᵢ, sᵢ₊₁\\right)}{rᵢ * rᵢ₊₁ + sᵢ ⋅ sᵢ₊₁}
+```
+
+[^HormannPresentation]: K. Hormann and N. Sukumar. Generalized Barycentric Coordinates in Computer Graphics and Computational Mechanics. Taylor & Fancis, CRC Press, 2017.
+```
+
+"""
+function t_value(sᵢ::_VecTypes{N, T1}, sᵢ₊₁::_VecTypes{N, T1}, rᵢ::T2, rᵢ₊₁::T2) where {N, T1 <: Real, T2 <: Real}
+ return _det(sᵢ, sᵢ₊₁) / muladd(rᵢ, rᵢ₊₁, dot(sᵢ, sᵢ₊₁))
+end
+
+
+function barycentric_coordinates!(λs::Vector{<: Real}, ::MeanValue, polypoints::AbstractVector{<: Point{2, T1}}, point::Point{2, T2}) where {T1 <: Real, T2 <: Real}
+ @boundscheck @assert length(λs) == length(polypoints)
+ @boundscheck @assert length(polypoints) >= 3
+ n_points = length(polypoints)
+ # Initialize counters and register variables
+ # Points - these are actually vectors from point to vertices
+ # polypoints[i-1], polypoints[i], polypoints[i+1]
+ sᵢ₋₁ = polypoints[end] - point
+ sᵢ = polypoints[begin] - point
+ sᵢ₊₁ = polypoints[begin+1] - point
+ # radius / Euclidean distance between points.
+ rᵢ₋₁ = norm(sᵢ₋₁)
+ rᵢ = norm(sᵢ )
+ rᵢ₊₁ = norm(sᵢ₊₁)
+ # Perform the first computation explicitly, so we can cut down on
+ # a mod in the loop.
+ λs[1] = (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ # Loop through the rest of the vertices, compute, store in λs
+ for i in 2:n_points
+ # Increment counters + set variables
+ sᵢ₋₁ = sᵢ
+ sᵢ = sᵢ₊₁
+ sᵢ₊₁ = polypoints[mod1(i+1, n_points)] - point
+ rᵢ₋₁ = rᵢ
+ rᵢ = rᵢ₊₁
+ rᵢ₊₁ = norm(sᵢ₊₁) # radius / Euclidean distance between points.
+ λs[i] = (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ end
+ # Normalize λs to the 1-norm (sum=1)
+ λs ./= sum(λs)
+ return λs
+end
julia
function barycentric_coordinates(::MeanValue, polypoints::NTuple{N, Point{2, T2}}, point::Point{2, T1},) where {N, T1, T2}
+ ## Initialize counters and register variables
+ ## Points - these are actually vectors from point to vertices
+ ## polypoints[i-1], polypoints[i], polypoints[i+1]
+ sᵢ₋₁ = polypoints[end] - point
+ sᵢ = polypoints[begin] - point
+ sᵢ₊₁ = polypoints[begin+1] - point
+ ## radius / Euclidean distance between points.
+ rᵢ₋₁ = norm(sᵢ₋₁)
+ rᵢ = norm(sᵢ )
+ rᵢ₊₁ = norm(sᵢ₊₁)
+ λ₁ = (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ λs = ntuple(N) do i
+ if i == 1
+ return λ₁
+ end
+ ## Increment counters + set variables
+ sᵢ₋₁ = sᵢ
+ sᵢ = sᵢ₊₁
+ sᵢ₊₁ = polypoints[mod1(i+1, N)] - point
+ rᵢ₋₁ = rᵢ
+ rᵢ = rᵢ₊₁
+ rᵢ₊₁ = norm(sᵢ₊₁) # radius / Euclidean distance between points.
+ return (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ end
+
+ ∑λ = sum(λs)
+
+ return ntuple(N) do i
+ λs[i] / ∑λ
+ end
+end
This performs an inplace accumulation, using less memory and is faster. That's particularly good if you are using a polygon with a large number of points...
julia
function barycentric_interpolate(::MeanValue, polypoints::AbstractVector{<: Point{2, T1}}, values::AbstractVector{V}, point::Point{2, T2}) where {T1 <: Real, T2 <: Real, V}
+ @boundscheck @assert length(values) == length(polypoints)
+ @boundscheck @assert length(polypoints) >= 3
+
+ n_points = length(polypoints)
+ # Initialize counters and register variables
+ # Points - these are actually vectors from point to vertices
+ # polypoints[i-1], polypoints[i], polypoints[i+1]
+ sᵢ₋₁ = polypoints[end] - point
+ sᵢ = polypoints[begin] - point
+ sᵢ₊₁ = polypoints[begin+1] - point
+ # radius / Euclidean distance between points.
+ rᵢ₋₁ = norm(sᵢ₋₁)
+ rᵢ = norm(sᵢ )
+ rᵢ₊₁ = norm(sᵢ₊₁)
+ # Now, we set the interpolated value to the first point's value, multiplied
+ # by the weight computed relative to the first point in the polygon.
+ wᵢ = (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ wₜₒₜ = wᵢ
+ interpolated_value = values[begin] * wᵢ
+ for i in 2:n_points
+ # Increment counters + set variables
+ sᵢ₋₁ = sᵢ
+ sᵢ = sᵢ₊₁
+ sᵢ₊₁ = polypoints[mod1(i+1, n_points)] - point
+ rᵢ₋₁ = rᵢ
+ rᵢ = rᵢ₊₁
+ rᵢ₊₁ = norm(sᵢ₊₁)
+ # Now, we calculate the weight:
+ wᵢ = (t_value(sᵢ₋₁, sᵢ, rᵢ₋₁, rᵢ) + t_value(sᵢ, sᵢ₊₁, rᵢ, rᵢ₊₁)) / rᵢ
+ # perform a weighted sum with the interpolated value:
+ interpolated_value += values[i] * wᵢ
+ # and add the weight to the total weight accumulator.
+ wₜₒₜ += wᵢ
+ end
+ # Return the normalized interpolated value.
+ return interpolated_value / wₜₒₜ
+end
When you have holes, then you have to be careful about the order you iterate around points.
Specifically, you have to iterate around each linear ring separately and ensure there are no degenerate/repeated points at the start and end!
The centroid is the geometric center of a line string or area(s). Note that the centroid does not need to be inside of a concave area.
Further note that by convention a line, or linear ring, is calculated by weighting the line segments by their length, while polygons and multipolygon centroids are calculated by weighting edge's by their 'area components'.
To provide an example, consider this concave polygon in the shape of a 'C':
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+cshape = GI.Polygon([[(0,0), (0,3), (3,3), (3,2), (1,2), (1,1), (3,1), (3,0), (0,0)]])
+f, a, p = poly(collect(GI.getpoint(cshape)); axis = (; aspect = DataAspect()))
Let's see what the centroid looks like (plotted in red):
julia
cent = GO.centroid(cshape)
+scatter!(GI.x(cent), GI.y(cent), color = :red)
+f
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Note that if you call centroid on a LineString or LinearRing, the centroid_and_length function will be called due to the weighting scheme described above, while centroid_and_area is called for polygons and multipolygons. However, centroid_and_area can still be called on a LineString or LinearRing when they are closed, for example as the interior hole of a polygon.
The helper functions centroid_and_length and centroid_and_area are made availible just in case the user also needs the area or length to decrease repeat computation.
julia
"""
+ centroid(geom, [T=Float64])::Tuple{T, T}
+
+Returns the centroid of a given line segment, linear ring, polygon, or
+mutlipolygon.
+"""
+centroid(geom, ::Type{T} = Float64; threaded=false) where T =
+ centroid(GI.trait(geom), geom, T; threaded)
+function centroid(
+ trait::Union{GI.LineStringTrait, GI.LinearRingTrait}, geom, ::Type{T}=Float64; threaded=false
+) where T
+ centroid_and_length(trait, geom, T)[1]
+end
+centroid(trait, geom, ::Type{T}; threaded=false) where T =
+ centroid_and_area(geom, T; threaded)[1]
+
+"""
+ centroid_and_length(geom, [T=Float64])::(::Tuple{T, T}, ::Real)
+
+Returns the centroid and length of a given line/ring. Note this is only valid
+for line strings and linear rings.
+"""
+centroid_and_length(geom, ::Type{T}=Float64) where T =
+ centroid_and_length(GI.trait(geom), geom, T)
+function centroid_and_length(
+ ::Union{GI.LineStringTrait, GI.LinearRingTrait}, geom, ::Type{T},
+) where T
xcentroid -= xinterior * interior_area
+ ycentroid -= yinterior * interior_area
+ end
+ xcentroid /= area
+ ycentroid /= area
+ return (xcentroid, ycentroid), area
+end
The op argument for _applyreduce and point / area It combines two (point, area) tuples into one, taking the average of the centroid points weighted by the area of the geom they are from.
julia
function _combine_centroid_and_area(((x1, y1), area1), ((x2, y2), area2))
+ area = area1 + area2
+ x = (x1 * area1 + x2 * area2) / area
+ y = (y1 * area1 + y2 * area2) / area
+ return (x, y), area
+end
This file contains the shared helper functions for the polygon clipping functionalities.
This enum defines which side of an edge a point is on
julia
@enum PointEdgeSide left=1 right=2 unknown=3
Constants assigned for readability
julia
const enter, exit = true, false
+const crossing, bouncing = true, false
+
+#= A point can either be the start or end of an overlapping chain of points between two
+polygons, or not an endpoint of a chain. =#
+@enum EndPointType start_chain=1 end_chain=2 not_endpoint=3
+
+#= This is the struct that makes up a_list and b_list. Many values are only used if point is
+an intersection point (ipt). =#
+@kwdef struct PolyNode{T <: AbstractFloat}
+ point::Tuple{T,T} # (x, y) values of given point
+ inter::Bool = false # If ipt, true, else 0
+ neighbor::Int = 0 # If ipt, index of equivalent point in a_list or b_list, else 0
+ idx::Int = 0 # If crossing point, index within sorted a_idx_list
+ ent_exit::Bool = false # If ipt, true if enter and false if exit, else false
+ crossing::Bool = false # If ipt, true if intersection crosses from out/in polygon, else false
+ endpoint::EndPointType = not_endpoint # If ipt, denotes if point is the start or end of an overlapping chain
+ fracs::Tuple{T,T} = (0., 0.) # If ipt, fractions along edges to ipt (a_frac, b_frac), else (0, 0)
+end
+
+#= Create a new node with all of the same field values as the given PolyNode unless
+alternative values are provided, in which case those should be used. =#
+PolyNode(node::PolyNode{T};
+ point = node.point, inter = node.inter, neighbor = node.neighbor, idx = node.idx,
+ ent_exit = node.ent_exit, crossing = node.crossing, endpoint = node.endpoint,
+ fracs = node.fracs,
+) where T = PolyNode{T}(;
+ point = point, inter = inter, neighbor = neighbor, idx = idx, ent_exit = ent_exit,
+ crossing = crossing, endpoint = endpoint, fracs = fracs)
Checks equality of two PolyNodes by backing point value, fractional value, and intersection status
This function takes in two polygon rings and calls '_build_a_list', '_build_b_list', and '_flag_ent_exit' in order to fully form a_list and b_list. The 'a_list' and 'b_list' that it returns are the fully updated vectors of PolyNodes that represent the rings 'poly_a' and 'poly_b', respectively. This function also returns 'a_idx_list', which at its "ith" index stores the index in 'a_list' at which the "ith" intersection point lies.
julia
function _build_ab_list(::Type{T}, poly_a, poly_b, delay_cross_f::F1, delay_bounce_f::F2; exact) where {T, F1, F2}
This function take in two polygon rings and creates a vector of PolyNodes to represent poly_a, including its intersection points with poly_b. The information stored in each PolyNode is needed for clipping using the Greiner-Hormann clipping algorithm.
Note: After calling this function, a_list is not fully formed because the neighboring indicies of the intersection points in b_list still need to be updated. Also we still have not update the entry and exit flags for a_list.
The a_idx_list is a list of the indicies of intersection points in a_list. The value at index i of a_idx_list is the location in a_list where the ith intersection point lies.
julia
function _build_a_list(::Type{T}, poly_a, poly_b; exact) where T
+ n_a_edges = _nedge(poly_a)
+ a_list = PolyNode{T}[] # list of points in poly_a
+ sizehint!(a_list, n_a_edges)
+ a_idx_list = Vector{Int}() # finds indices of intersection points in a_list
+ a_count = 0 # number of points added to a_list
+ n_b_intrs = 0
Loop through points of poly_a
julia
local a_pt1
+ for (i, a_p2) in enumerate(GI.getpoint(poly_a))
+ a_pt2 = (T(GI.x(a_p2)), T(GI.y(a_p2)))
+ if i <= 1 || (a_pt1 == a_pt2) # don't repeat points
+ a_pt1 = a_pt2
+ continue
+ end
Add the first point of the edge to the list of points in a_list
This function takes in the a_list and a_idx_list build in _build_a_list and poly_b and creates a vector of PolyNodes to represent poly_b. The information stored in each PolyNode is needed for clipping using the Greiner-Hormann clipping algorithm.
Note: after calling this function, b_list is not fully updated. The entry/exit flags still need to be updated. However, the neightbor value in a_list is now updated.
julia
function _build_b_list(::Type{T}, a_idx_list, a_list, n_b_intrs, poly_b) where T
Sort intersection points by insertion order in b_list
julia
sort!(a_idx_list, by = x-> a_list[x].neighbor + a_list[x].fracs[2])
Loop over points in poly_b and add each point and intersection point
julia
local b_pt1
+ for (i, b_p2) in enumerate(GI.getpoint(poly_b))
+ b_pt2 = _tuple_point(b_p2, T)
+ if i ≤ 1 || (b_pt1 == b_pt2) # don't repeat points
+ b_pt1 = b_pt2
+ continue
+ end
+ b_count += 1
+ push!(b_list, PolyNode{T}(; point = b_pt1))
+ if intr_curr ≤ n_intr_pts
+ curr_idx = a_idx_list[intr_curr]
+ curr_node = a_list[curr_idx]
+ prev_counter = b_count
+ while curr_node.neighbor == i - 1 # Add all intersection points on current edge
+ b_idx = 0
+ new_intr = PolyNode(curr_node; neighbor = curr_idx)
+ if curr_node.fracs[2] == 0 # if curr_node is segment start point
intersection point is vertex of b
julia
b_idx = prev_counter
+ b_list[b_idx] = new_intr
+ else
+ b_count += 1
+ b_idx = b_count
+ push!(b_list, new_intr)
+ end
+ a_list[curr_idx] = PolyNode(curr_node; neighbor = b_idx)
+ intr_curr += 1
+ intr_curr > n_intr_pts && break
+ curr_idx = a_idx_list[intr_curr]
+ curr_node = a_list[curr_idx]
+ end
+ end
+ b_pt1 = b_pt2
+ end
+ sort!(a_idx_list) # return a_idx_list to order of points in a_list
+ return b_list
+end
_classify_crossing!(T, poly_b, a_list; exact)
This function marks all intersection points as either bouncing or crossing points. "Delayed" crossing or bouncing intersections (a chain of edges where the central edges overlap and thus only the first and last edge of the chain determine if the chain is bounding or crossing) are marked as follows: the first and the last points are marked as crossing if the chain is crossing and delayed otherwise and all middle points are marked as bouncing. Additionally, the start and end points of the chain are marked as endpoints using the endpoints field.
julia
function _classify_crossing!(::Type{T}, a_list, b_list; exact) where T
+ napts = length(a_list)
+ nbpts = length(b_list)
_is_vertex(pt) = !pt.inter || pt.fracs[1] == 0 || pt.fracs[1] == 1 || pt.fracs[2] == 0 || pt.fracs[2] == 1
+
+#= Determines which side (right or left) of the segment a_prev-curr_pt-a_next the points
+b_prev and b_next are on. Given this is only called when curr_pt is an intersection point
+that wasn't initially classified as crossing, we know that curr_pt is either from a hinge or
+overlapping intersection and thus is an original vertex of either poly_a or poly_b. Due to
+floating point error when calculating new intersection points, we only want to use original
+vertices to determine orientation. Thus, for other points, find nearest point that is a
+vertex. Given other intersection points will be collinear along existing segments, this
+won't change the orientation. =#
+function _get_sides(b_prev, b_next, a_prev, curr_pt, a_next, i, j, a_list, b_list; exact)
+ b_prev_pt = if _is_vertex(b_prev)
+ b_prev.point
+ else # Find original start point of segment formed by b_prev and curr_pt
+ prev_idx = findprev(_is_vertex, b_list, j - 1)
+ prev_idx = isnothing(prev_idx) ? findlast(_is_vertex, b_list) : prev_idx
+ b_list[prev_idx].point
+ end
+ b_next_pt = if _is_vertex(b_next)
+ b_next.point
+ else # Find original end point of segment formed by curr_pt and b_next
+ next_idx = findnext(_is_vertex, b_list, j + 1)
+ next_idx = isnothing(next_idx) ? findfirst(_is_vertex, b_list) : next_idx
+ b_list[next_idx].point
+ end
+ a_prev_pt = if _is_vertex(a_prev)
+ a_prev.point
+ else # Find original start point of segment formed by a_prev and curr_pt
+ prev_idx = findprev(_is_vertex, a_list, i - 1)
+ prev_idx = isnothing(prev_idx) ? findlast(_is_vertex, a_list) : prev_idx
+ a_list[prev_idx].point
+ end
+ a_next_pt = if _is_vertex(a_next)
+ a_next.point
+ else # Find original end point of segment formed by curr_pt and a_next
+ next_idx = findnext(_is_vertex, a_list, i + 1)
+ next_idx = isnothing(next_idx) ? findfirst(_is_vertex, a_list) : next_idx
+ a_list[next_idx].point
+ end
Determines if Q lies to the left or right of the line formed by P1-P2-P3
julia
function _get_side(Q, P1, P2, P3; exact)
+ s1 = Predicates.orient(Q, P1, P2; exact)
+ s2 = Predicates.orient(Q, P2, P3; exact)
+ s3 = Predicates.orient(P1, P2, P3; exact)
+
+ side = if s3 ≥ 0
+ (s1 < 0) || (s2 < 0) ? right : left
+ else # s3 < 0
+ (s1 > 0) || (s2 > 0) ? left : right
+ end
+ return side
+end
+
+#= Given a list of PolyNodes, find the first element that isn't an intersection point. Then,
+test if this element is in or out of the given polygon. Return the next index, as well as
+the enter/exit status of the next intersection point (the opposite of the in/out check). If
+all points are intersection points, find the first element that either is the end of a chain
+or a crossing point that isn't in a chain. Then take the midpoint of this point and the next
+point in the list and perform the in/out check. If none of these points exist, return
+a `next_idx` of `nothing`. =#
+function _pt_off_edge_status(::Type{T}, pt_list, poly, npts; exact) where T
+ start_idx, is_non_intr_pt = findfirst(_is_not_intr, pt_list), true
+ if isnothing(start_idx)
+ start_idx, is_non_intr_pt = findfirst(_next_edge_off, pt_list), false
+ isnothing(start_idx) && return (start_idx, false)
+ end
+ next_idx = start_idx < npts ? (start_idx + 1) : 1
+ start_pt = if is_non_intr_pt
+ pt_list[start_idx].point
+ else
+ (pt_list[start_idx].point .+ pt_list[next_idx].point) ./ 2
+ end
+ start_status = !_point_filled_curve_orientation(start_pt, poly; in = true, on = false, out = false, exact)
+ return next_idx, start_status
+end
Check if a PolyNode is an intersection point
julia
_is_not_intr(pt) = !pt.inter
+#= Check if a PolyNode is the last point of a chain or a non-overlapping crossing point.
+The next midpoint of one of these points and the next point within a polygon must not be on
+the polygon edge. =#
+_next_edge_off(pt) = (pt.endpoint == end_chain) || (pt.crossing && pt.endpoint == not_endpoint)
This function flags all the intersection points as either an 'entry' or 'exit' point in relation to the given polygon. For non-delayed crossings we simply alternate the enter/exit status. This also holds true for the first and last points of a delayed bouncing, where they both have an opposite entry/exit flag. Conversely, the first and last point of a delayed crossing have the same entry/exit status. Furthermore, the crossing/bouncing flag of delayed crossings and bouncings may be updated. This depends on function specific rules that determine which of the start or end points (if any) should be marked as crossing for used during polygon tracing. A consistent rule is that the start and end points of a delayed crossing will have different crossing/bouncing flags, while a the endpoints of a delayed bounce will be the same.
Used for clipping polygons by other polygons.
julia
function _flag_ent_exit!(::Type{T}, ::GI.LinearRingTrait, poly, pt_list, delay_cross_f, delay_bounce_f; exact) where T
+ npts = length(pt_list)
start_chain_idx = 0
+ for ii in Iterators.flatten((next_idx:npts, 1:start_idx))
+ curr_pt = pt_list[ii]
+ if curr_pt.endpoint == start_chain
+ start_chain_idx = ii
+ elseif curr_pt.crossing || curr_pt.endpoint == end_chain
+ start_crossing, end_crossing = curr_pt.crossing, curr_pt.crossing
+ if curr_pt.endpoint == end_chain # ending overlapping chain
+ start_pt = pt_list[start_chain_idx]
+ if curr_pt.crossing # delayed crossing
+ #= start and end crossing status are different and depend on current
+ entry/exit status =#
+ start_crossing, end_crossing = delay_cross_f(status)
+ else # delayed bouncing
+ next_idx = ii < npts ? (ii + 1) : 1
+ next_val = (curr_pt.point .+ pt_list[next_idx].point) ./ 2
+ pt_in_poly = _point_filled_curve_orientation(next_val, poly; in = true, on = false, out = false, exact)
+ #= start and end crossing status are the same and depend on if adjacent
+ edges of pt_list are within poly =#
+ start_crossing = delay_bounce_f(pt_in_poly)
+ end_crossing = start_crossing
+ end
update start of chain point
julia
pt_list[start_chain_idx] = PolyNode(start_pt; ent_exit = status, crossing = start_crossing)
+ if !curr_pt.crossing
+ status = !status
+ end
+ end
+ pt_list[ii] = PolyNode(curr_pt; ent_exit = status, crossing = end_crossing)
+ status = !status
+ end
+ end
+ return
+end
This function flags all the intersection points as either an 'entry' or 'exit' point in relation to the given line. Returns true if there are crossing points to classify, else returns false. Used for cutting polygons by lines.
Assumes that the first point is outside of the polygon and not on an edge.
julia
function _flag_ent_exit!(::GI.LineTrait, poly, pt_list; exact)
+ status = !_point_filled_curve_orientation(pt_list[1].point, poly; in = true, on = false, out = false, exact)
Loop over points and mark entry and exit status
julia
for (ii, curr_pt) in enumerate(pt_list)
+ if curr_pt.crossing
+ pt_list[ii] = PolyNode(curr_pt; ent_exit = status)
+ status = !status
+ end
+ end
+ return
+end
+
+#= Filters a_idx_list to just include crossing points and sets the index of all crossing
+points (which element they correspond to within a_idx_list). =#
+function _index_crossing_intrs!(a_list, b_list, a_idx_list)
+ filter!(x -> a_list[x].crossing, a_idx_list)
+ for (i, a_idx) in enumerate(a_idx_list)
+ curr_node = a_list[a_idx]
+ neighbor_node = b_list[curr_node.neighbor]
+ a_list[a_idx] = PolyNode(curr_node; idx = i)
+ b_list[curr_node.neighbor] = PolyNode(neighbor_node; idx = i)
+ end
+ return
+end
This function takes the outputs of _build_ab_list and traces the lists to determine which polygons are formed as described in Greiner and Hormann. The function f_step determines in which direction the lists are traced. This function is different for intersection, difference, and union. f_step must take in two arguments: the most recent intersection node's entry/exit status and a boolean that is true if we are currently tracing a_list and false if we are tracing b_list. The functions used for each clipping operation are follows: - Intersection: (x, y) -> x ? 1 : (-1) - Difference: (x, y) -> (x ⊻ y) ? 1 : (-1) - Union: (x, y) -> x ? (-1) : 1
A list of GeoInterface polygons is returned from this function.
Note: poly_a and poly_b are temporary inputs used for debugging and can be removed eventually.
same_status, prev_status = true, curr.ent_exit
+ while same_status
+ @assert visited_pts < total_pts "Clipping tracing hit every point - clipping error. Please open an issue with polygons: $(GI.coordinates(poly_a)) and $(GI.coordinates(poly_b))."
For polygns with no crossing intersection points, either one polygon is inside of another, or they are seperate polygons with no intersection (other than an edge or point).
Return two booleans that represent if a is inside b (potentially with shared edges / points) and visa versa if b is inside of a.
julia
function _find_non_cross_orientation(a_list, b_list, a_poly, b_poly; exact)
+ non_intr_a_idx = findfirst(x -> !x.inter, a_list)
+ non_intr_b_idx = findfirst(x -> !x.inter, b_list)
+ #= Determine if non-intersection point is in or outside of polygon - if there isn't A
+ non-intersection point, then all points are on the polygon edge =#
+ a_pt_orient = isnothing(non_intr_a_idx) ? point_on :
+ _point_filled_curve_orientation(a_list[non_intr_a_idx].point, b_poly; exact)
+ b_pt_orient = isnothing(non_intr_b_idx) ? point_on :
+ _point_filled_curve_orientation(b_list[non_intr_b_idx].point, a_poly; exact)
+ a_in_b = a_pt_orient != point_out && b_pt_orient != point_in
+ b_in_a = b_pt_orient != point_out && a_pt_orient != point_in
+ return a_in_b, b_in_a
+end
The holes specified by the hole iterator are added to the polygons in the return_polys list. If this creates more polygons, they are added to the end of the list. If this removes polygons, they are removed from the list
julia
function _add_holes_to_polys!(::Type{T}, return_polys, hole_iterator, remove_poly_idx; exact) where T
+ n_polys = length(return_polys)
+ remove_hole_idx = Int[]
Remove set of holes from all polygons
julia
for i in 1:n_polys
+ n_new_per_poly = 0
+ for curr_hole in Iterators.map(tuples, hole_iterator) # loop through all holes
loop through all pieces of original polygon (new pieces added to end of list)
julia
for j in Iterators.flatten((i:i, (n_polys + 1):(n_polys + n_new_per_poly)))
+ curr_poly = return_polys[j]
+ remove_poly_idx[j] && continue
+ curr_poly_ext = GI.nhole(curr_poly) > 0 ? GI.Polygon(StaticArrays.SVector(GI.getexterior(curr_poly))) : curr_poly
+ in_ext, on_ext, out_ext = _line_polygon_interactions(curr_hole, curr_poly_ext; exact, closed_line = true)
+ if in_ext # hole is at least partially within the polygon's exterior
+ new_hole, new_hole_poly, n_new_pieces = _combine_holes!(T, curr_hole, curr_poly, return_polys, remove_hole_idx)
+ if n_new_pieces > 0
+ append!(remove_poly_idx, falses(n_new_pieces))
+ n_new_per_poly += n_new_pieces
+ end
+ if !on_ext && !out_ext # hole is completly within exterior
+ push!(curr_poly.geom, new_hole)
+ else # hole is partially within and outside of polygon's exterior
+ new_polys = difference(curr_poly_ext, new_hole_poly, T; target=GI.PolygonTrait())
+ n_new_polys = length(new_polys) - 1
replace original
julia
curr_poly.geom[1] = GI.getexterior(new_polys[1])
+ append!(curr_poly.geom, GI.gethole(new_polys[1]))
+ if n_new_polys > 0 # add any extra pieces
+ append!(return_polys, @view new_polys[2:end])
+ append!(remove_poly_idx, falses(n_new_polys))
+ n_new_per_poly += n_new_polys
+ end
+ end
polygon is completly within hole
julia
elseif coveredby(curr_poly_ext, GI.Polygon(StaticArrays.SVector(curr_hole)))
+ remove_poly_idx[j] = true
+ end
+ end
+ end
+ n_polys += n_new_per_poly
+ end
The new hole is combined with any existing holes in curr_poly. The holes can be combined into a larger hole if they are intersecting. If this happens, then the new, combined hole is returned with the orignal holes making up the new hole removed from curr_poly. Additionally, if the combined holes form a ring, the interior is added to the return_polys as a new polygon piece. Additionally, holes leftover after combination will be checked for it they are in the "main" polygon or in one of these new pieces and moved accordingly.
If the holes don't touch or curr_poly has no holes, then new_hole is returned without any changes.
julia
function _combine_holes!(::Type{T}, new_hole, curr_poly, return_polys, remove_hole_idx) where T
+ n_new_polys = 0
+ empty!(remove_hole_idx)
+ new_hole_poly = GI.Polygon(StaticArrays.SVector(new_hole))
Combine any existing holes in curr_poly with new hole
julia
for (k, old_hole) in enumerate(GI.gethole(curr_poly))
+ old_hole_poly = GI.Polygon(StaticArrays.SVector(old_hole))
+ if intersects(new_hole_poly, old_hole_poly)
If the holes intersect, combine them into a bigger hole
julia
hole_union = union(new_hole_poly, old_hole_poly, T; target = GI.PolygonTrait())[1]
+ push!(remove_hole_idx, k + 1)
+ new_hole = GI.getexterior(hole_union)
+ new_hole_poly = GI.Polygon(StaticArrays.SVector(new_hole))
+ n_pieces = GI.nhole(hole_union)
+ if n_pieces > 0 # if the hole has a hole, then this is a new polygon piece!
+ append!(return_polys, [GI.Polygon([h]) for h in GI.gethole(hole_union)])
+ n_new_polys += n_pieces
+ end
+ end
+ end
If new polygon pieces created, make sure remaining holes are in the correct piece
julia
@views for piece in return_polys[end - n_new_polys + 1:end]
+ for (k, old_hole) in enumerate(GI.gethole(curr_poly))
+ if !(k in remove_hole_idx) && within(old_hole, piece)
+ push!(remove_hole_idx, k + 1)
+ push!(piece.geom, old_hole)
+ end
+ end
+ end
+ deleteat!(curr_poly.geom, remove_hole_idx)
+ return new_hole, new_hole_poly, n_new_polys
+end
+
+#= Remove collinear edge points, other than the first and last edge vertex, to simplify
+polygon - including both the exterior ring and any holes=#
+function _remove_collinear_points!(polys, remove_idx, poly_a, poly_b)
+ for (i, poly) in Iterators.reverse(enumerate(polys))
+ for (j, ring) in Iterators.reverse(enumerate(GI.getring(poly)))
+ n = length(ring.geom)
resize and reset removing index buffer
julia
resize!(remove_idx, n)
+ fill!(remove_idx, false)
+ local p1, p2
+ for (i, p) in enumerate(ring.geom)
+ if i == 1
+ p1 = p
+ continue
+ elseif i == 2
+ p2 = p
+ continue
+ else
+ p3 = p
check if p2 is approximatly on the edge formed by p1 and p3 - remove if so
julia
if Predicates.orient(p1, p2, p3; exact = _False()) == 0
+ remove_idx[i - 1] = true
+ end
+ end
+ p1, p2 = p2, p3
+ end
Check if the first point (which is repeated as the last point) is needed
julia
if Predicates.orient(ring.geom[end - 1], ring.geom[1], ring.geom[2]; exact = _False()) == 0
+ remove_idx[1], remove_idx[end] = true, true
+ end
Remove unneeded collinear points
julia
deleteat!(ring.geom, remove_idx)
Check if enough points are left to form a polygon
julia
if length(ring.geom) ≤ (remove_idx[1] ? 2 : 3)
+ if j == 1
+ deleteat!(polys, i)
+ break
+ else
+ deleteat!(poly.geom, j)
+ continue
+ end
+ end
+ if remove_idx[1] # make sure the last point is repeated
+ push!(ring.geom, ring.geom[1])
+ end
+ end
+ end
+ return
+end
Coverage is the amount of geometry area within a bounding box defined by the minimum and maximum x and y-coordiantes of that bounding box, or an Extent containing that information.
To provide an example, consider this rectangle:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+rect = GI.Polygon([[(-1,0), (-1,1), (1,1), (1,0), (-1,0)]])
+cell = GI.Polygon([[(0, 0), (0, 2), (2, 2), (2, 0), (0, 0)]])
+xmin, xmax, ymin, ymax = 0, 2, 0, 2
+f, a, p = poly(collect(GI.getpoint(cell)); axis = (; aspect = DataAspect()))
+poly!(collect(GI.getpoint(rect)))
+f
It is clear that half of the polygon is within the cell, so the coverage should be 1.0, half of the area of the rectangle.
This is the GeoInterface-compatible implementation. First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Note that the coverage is zero for all points and curves, even if the curves are closed like with a linear ring.
const UNKNOWN, NORTH, EAST, SOUTH, WEST = 0:4
+
+"""
+ coverage(geom, xmin, xmax, ymin, ymax, [T = Float64])::T
+
+Returns the area of intersection between given geometry and grid cell defined by its minimum
+and maximum x and y-values. This is computed differently for different geometries:
+
+- The signed area of a point is always zero.
+- The signed area of a curve is always zero.
+- The signed area of a polygon is calculated by tracing along its edges and switching to the
+ cell edges if needed.
+- The coverage of a geometry collection, multi-geometry, feature collection of
+ array/iterable is the sum of the coverages of all of the sub-geometries.
+
+Result will be of type T, where T is an optional argument with a default value
+of Float64.
+"""
+function coverage(geom, xmin, xmax, ymin, ymax,::Type{T} = Float64; threaded=false) where T <: AbstractFloat
+ applyreduce(+, _COVERAGE_TARGETS, geom; threaded, init=zero(T)) do g
+ _coverage(T, GI.trait(g), g, T(xmin), T(xmax), T(ymin), T(ymax))
+ end
+end
+
+function coverage(geom, cell_ext::Extents.Extent, ::Type{T} = Float64; threaded=false) where T <: AbstractFloat
+ (xmin, xmax), (ymin, ymax) = values(cell_ext)
+ return coverage(geom, xmin, xmax, ymin, ymax, T; threaded = threaded)
+end
Points, MultiPoints, Curves, MultiCurves
julia
_coverage(::Type{T}, ::GI.AbstractGeometryTrait, geom, xmin, xmax, ymin, ymax; kwargs...) where T = zero(T)
for hole in GI.gethole(poly)
+ cov_area -= _coverage(T, hole, xmin, xmax, ymin, ymax; exact)
+ end
+ return cov_area
+end
+
+#= Calculates the area of the filled ring within the cell defined by corners with (xmin, ymin),
+(xmin, ymax), (xmax, ymax), and (xmax, ymin). =#
+function _coverage(::Type{T}, ring, xmin, xmax, ymin, ymax; exact) where T
+ cov_area = zero(T)
+ unmatched_out_wall, unmatched_out_point = UNKNOWN, (zero(T), zero(T))
+ unmatched_in_wall, unmatched_in_point = unmatched_out_wall, unmatched_out_point
Loop over edges of polygon
julia
start_idx = 1
+ for (i, p) in enumerate(GI.getpoint(ring))
+ if !_point_in_cell(p, xmin, xmax, ymin, ymax)
+ start_idx = i
+ break
+ end
+ end
+ ring_cw = isclockwise(ring)
+ p1 = _tuple_point(GI.getpoint(ring, start_idx), T)
Must rotate clockwise for the algorithm to work
julia
point_idx = ring_cw ? Iterators.flatten((start_idx + 1:GI.npoint(ring), 1:start_idx)) :
+ Iterators.flatten((start_idx - 1:-1:1, GI.npoint(ring):-1:start_idx))
+ for i in point_idx
+ p2 = _tuple_point(GI.getpoint(ring, i), T)
Returns true if b is between a and c, exclusive of the maximum value, else false.
julia
_between(b, a, c) = a ≤ b < c || c ≤ b < a
+
+#= Determine intersections of the line from (x1, y1) to (x2, y2) with the bounding box
+defined by the minimum and maximum x/y values. Since we are dealing with a single line
+segment, we know that there is at maximum two intersection points.
+
+For each intersection point that we find, return the wall that it passes through, as well as
+the intersection point itself as a a tuple. If an intersection point isn't found, return the
+wall as UNKNOWN and the point as a pair of zeros. =#
+function _line_intersect_cell(::Type{T}, (x1, y1), (x2, y2), xmin, xmax, ymin, ymax) where T
+ Δx, Δy = x2 - x1, y2 - y1
+ inter1 = (UNKNOWN, (zero(T), zero(T)))
+ inter2 = inter1
+ if Δx == 0 # If line is vertical, only consider north and south
+ if xmin ≤ x1 ≤ xmax
+ inter1 = _between(ymax, y1, y2) ? (NORTH, (x1, ymax)) : inter1
+ inter2 = _between(ymin, y1, y2) ? (SOUTH, (x1, ymin)) : inter2
+ end
+ elseif Δy == 0 # If line is horizontal, only consider east and west
+ if ymin ≤ y1 ≤ ymax
+ inter1 = _between(xmax, x1, x2) ? (EAST, (xmax, y1)) : inter1
+ inter2 = _between(xmin, x1, x2) ? (WEST, (xmin, y1)) : inter2
+ end
+ else # Line is tilted, must consider all edges, but only two can intersect
+ m = Δy / Δx
+ b = y1 - m * x1
Calculate and check potential intersections
julia
xn = (ymax - b) / m
+ if xmin ≤ xn ≤ xmax && _between(xn, x1, x2) && _between(ymax, y1, y2)
+ inter1 = (NORTH, (xn, ymax))
+ end
+ xs = (ymin - b) / m
+ if xmin ≤ xs ≤ xmax && _between(xs, x1, x2) && _between(ymin, y1, y2)
+ new_intr = (SOUTH, (xs, ymin))
+ (inter1[1] == UNKNOWN) ? (inter1 = new_intr) : (inter2 = new_intr)
+ end
+ ye = m * xmax + b
+ if ymin ≤ ye ≤ ymax && _between(ye, y1, y2) && _between(xmax, x1, x2)
+ new_intr = (EAST, (xmax, ye))
+ (inter1[1] == UNKNOWN) ? (inter1 = new_intr) : (inter2 = new_intr)
+ end
+ yw = m * xmin + b
+ if ymin ≤ yw ≤ ymax && _between(yw, y1, y2) && _between(xmin, x1, x2)
+ new_intr = (WEST, (xmin, yw))
+ (inter1[1] == UNKNOWN) ? (inter1 = new_intr) : (inter2 = new_intr)
+ end
+ end
+ if inter1[1] == UNKNOWN # first intersection must be known, if one exists
+ inter1, inter2 = inter2, inter1
+ end
+ return inter1, inter2
+end
Finds point of cell edge between p1 and p2 given which walls they are on
julia
function find_point_on_cell(p1, p2, wall1, wall2, xmin, xmax, ymin, ymax)
+ x1, y1 = p1
+ x2, y2 = p2
+ mid_point = if wall1 == wall2 && _is_clockwise_from(p1, p2, wall1)
+ (x1 + x2) / 2, (y1 + y2) / 2
+ elseif wall1 == NORTH
+ (xmax, ymax)
+ elseif wall1 == EAST
+ (xmax, ymin)
+ elseif wall1 == SOUTH
+ (xmin, ymin)
+ else
+ (xmin, ymax)
+ end
+ return mid_point
+end
+
+#= Area component of shoelace formula coming from the distance between point 1 and point 2
+along grid cell walls in between the two points. =#
+function connect_edges(::Type{T}, p1, p2, wall1, wall2, xmin, xmax, ymin, ymax) where {T}
+ connect_area = zero(T)
+ if wall1 == wall2 && _is_clockwise_from(p1, p2, wall1)
+ connect_area += _area_component(p1, p2)
+ else
True if (x1, y1) is clockwise from (x2, y2) on the same wall
julia
_is_clockwise_from((x1, y1), (x2, y2), wall) = (wall == NORTH && x2 > x1) ||
+ (wall == EAST && y2 < y1) || (wall == SOUTH && x2 < x1) || (wall == WEST && y2 > y1)
+
+#= Returns the area component of a full edge of the bounding box defined by the min and max
+values and the wall. =#
+_full_edge_area(xmin, xmax, ymin, ymax, wall) = if wall == NORTH
+ ymax * (xmin - xmax)
+ elseif wall == EAST
+ xmax * (ymin - ymax)
+ elseif wall == SOUTH
+ ymin * (xmax - xmin)
+ else
+ xmin * (ymax - ymin)
+ end
+
+#= Returns the area component of part of one wall, from its "starting corner" (going
+clockwise) to the point (x2, y2). =#
+function _partial_edge_in_area((x2, y2), xmin, xmax, ymin, ymax, wall)
+ x_wall = (wall == NORTH || wall == WEST) ? xmin : xmax
+ y_wall = (wall == NORTH || wall == EAST) ? ymax : ymin
+ return x_wall * y2 - x2 * y_wall
+end
+
+#= Returns the area component of part of one wall, from the point (x1, y1) to its
+"ending corner" (going clockwise). =#
+function _partial_edge_out_area((x1, y1), xmin, xmax, ymin, ymax, wall)
+ x_wall = (wall == NORTH || wall == EAST) ? xmax : xmin
+ y_wall = (wall == NORTH || wall == WEST) ? ymax : ymin
+ return x1 * y_wall - x_wall * y1
+end
This function depends on polygon clipping helper function and is inspired by the Greiner-Hormann clipping algorithm used elsewhere in this library. The inspiration came from this Stack Overflow discussion.
julia
"""
+ cut(geom, line, [T::Type])
+
+Return given geom cut by given line as a list of geometries of the same type as the input
+geom. Return the original geometry as only list element if none are found. Line must cut
+fully through given geometry or the original geometry will be returned.
+
+Note: This currently doesn't work for degenerate cases there line crosses through vertices.
+
+# Example
+
+```jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+poly = GI.Polygon([[(0.0, 0.0), (10.0, 0.0), (10.0, 10.0), (0.0, 10.0), (0.0, 0.0)]])
+line = GI.Line([(5.0, -5.0), (5.0, 15.0)])
+cut_polys = GO.cut(poly, line)
+GI.coordinates.(cut_polys)
output
julia
2-element Vector{Vector{Vector{Vector{Float64}}}}:
+ [[[0.0, 0.0], [5.0, 0.0], [5.0, 10.0], [0.0, 10.0], [0.0, 0.0]]]
+ [[[5.0, 0.0], [10.0, 0.0], [10.0, 10.0], [5.0, 10.0], [5.0, 0.0]]]
+```
+"""
+cut(geom, line, ::Type{T} = Float64) where {T <: AbstractFloat} =
+ _cut(T, GI.trait(geom), geom, GI.trait(line), line; exact = _True())
+
+#= Cut a given polygon by given line. Add polygon holes back into resulting pieces if there
+are any holes. =#
+function _cut(::Type{T}, ::GI.PolygonTrait, poly, ::GI.LineTrait, line; exact) where T
+ ext_poly = GI.getexterior(poly)
+ poly_list, intr_list = _build_a_list(T, ext_poly, line; exact)
+ n_intr_pts = length(intr_list)
If an impossible number of intersection points, return original polygon
julia
if n_intr_pts < 2 || isodd(n_intr_pts)
+ return [tuples(poly)]
+ end
function _cut(::Type{T}, trait::GI.AbstractTrait, geom, line; kwargs...) where T
+ @assert(
+ false,
+ "Cutting of $trait isn't implemented yet.",
+ )
+ return nothing
+end
+
+#= Cutting algorithm inspired by Greiner and Hormann clipping algorithm. Returns coordinates
+of cut geometry in Vector{Vector{Tuple}} format.
+
+Note: degenerate cases where intersection points are vertices do not work right now. =#
+function _cut(::Type{T}, geom, line, geom_list, intr_list, n_intr_pts; exact) where T
Sort and catagorize the intersection points
julia
sort!(intr_list, by = x -> geom_list[x].fracs[2])
+ _flag_ent_exit!(GI.LineTrait(), line, geom_list; exact)
export difference
+
+
+"""
+ difference(geom_a, geom_b, [T::Type]; target::Type, fix_multipoly = UnionIntersectingPolygons())
+
+Return the difference between two geometries as a list of geometries. Return an empty list
+if none are found. The type of the list will be constrained as much as possible given the
+input geometries. Furthermore, the user can provide a `taget` type as a keyword argument and
+a list of target geometries found in the difference will be returned. The user can also
+provide a float type that they would like the points of returned geometries to be. If the
+user is taking a intersection involving one or more multipolygons, and the multipolygon
+might be comprised of polygons that intersect, if `fix_multipoly` is set to an
+`IntersectingPolygons` correction (the default is `UnionIntersectingPolygons()`), then the
+needed multipolygons will be fixed to be valid before performing the intersection to ensure
+a correct answer. Only set `fix_multipoly` to false if you know that the multipolygons are
+valid, as it will avoid unneeded computation.
+
+# Example
+
+```jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+poly1 = GI.Polygon([[[0.0, 0.0], [5.0, 5.0], [10.0, 0.0], [5.0, -5.0], [0.0, 0.0]]])
+poly2 = GI.Polygon([[[3.0, 0.0], [8.0, 5.0], [13.0, 0.0], [8.0, -5.0], [3.0, 0.0]]])
+diff_poly = GO.difference(poly1, poly2; target = GI.PolygonTrait())
+GI.coordinates.(diff_poly)
output
julia
1-element Vector{Vector{Vector{Vector{Float64}}}}:
+ [[[6.5, 3.5], [5.0, 5.0], [0.0, 0.0], [5.0, -5.0], [6.5, -3.5], [3.0, 0.0], [6.5, 3.5]]]
+```
+"""
+function difference(
+ geom_a, geom_b, ::Type{T} = Float64; target=nothing, kwargs...,
+) where {T<:AbstractFloat}
+ return _difference(
+ TraitTarget(target), T, GI.trait(geom_a), geom_a, GI.trait(geom_b), geom_b;
+ exact = _True(), kwargs...,
+ )
+end
+
+#= The 'difference' function returns the difference of two polygons as a list of polygons.
+The algorithm to determine the difference was adapted from "Efficient clipping of efficient
+polygons," by Greiner and Hormann (1998). DOI: https://doi.org/10.1145/274363.274364 =#
+function _difference(
+ ::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.PolygonTrait, poly_a,
+ ::GI.PolygonTrait, poly_b;
+ exact, kwargs...
+) where T
add case for if they polygons are the same (all intersection points!) add a find_first check to find first non-inter poly!
julia
if b_in_a && !a_in_b # b in a and can't be the same polygon
+ poly_a_b_hole = GI.Polygon([tuples(ext_a), tuples(ext_b)])
+ push!(polys, poly_a_b_hole)
+ elseif !b_in_a && !a_in_b # polygons don't intersect
+ push!(polys, tuples(poly_a))
+ return polys
+ end
+ end
+ remove_idx = falses(length(polys))
If the original polygons had holes, take that into account.
julia
if GI.nhole(poly_a) != 0
+ _add_holes_to_polys!(T, polys, GI.gethole(poly_a), remove_idx; exact)
+ end
+ if GI.nhole(poly_b) != 0
+ for hole in GI.gethole(poly_b)
+ hole_poly = GI.Polygon(StaticArrays.SVector(hole))
+ new_polys = intersection(hole_poly, poly_a, T; target = GI.PolygonTrait)
+ if length(new_polys) > 0
+ append!(polys, new_polys)
+ end
+ end
+ end
Helper functions for Differences with Greiner and Hormann Polygon Clipping
julia
#= When marking the crossing status of a delayed crossing, the chain start point is crossing
+when the start point is a entry point and is a bouncing point when the start point is an
+exit point. The end of the chain has the opposite crossing / bouncing status. =#
+_diff_delay_cross_f(x) = (x, !x)
+#= When marking the crossing status of a delayed bouncing, the chain start and end points
+are crossing if the current polygon's adjacent edges are within the non-tracing polygon and
+we are tracing b_list or if the edges are outside and we are on a_list. Otherwise the
+endpoints are marked as crossing. x is a boolean representing if the edges are inside or
+outside of the polygon and y is a variable that is true if we are on a_list and false if we
+are on b_list. =#
+_diff_delay_bounce_f(x, y) = x ⊻ y
+#= When tracing polygons, step forwards if the most recent intersection point was an entry
+point and we are currently tracing b_list or if it was an exit point and we are currently
+tracing a_list, else step backwards, where x is the entry/exit status and y is a variable
+that is true if we are on a_list and false if we are on b_list. =#
+_diff_step(x, y) = (x ⊻ y) ? 1 : (-1)
+
+#= Polygon with multipolygon difference - note that all intersection regions between
+`poly_a` and any of the sub-polygons of `multipoly_b` are removed from `poly_a`. =#
+function _difference(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.PolygonTrait, poly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ kwargs...,
+) where T
+ polys = [tuples(poly_a, T)]
+ for poly_b in GI.getpolygon(multipoly_b)
+ isempty(polys) && break
+ polys = mapreduce(p -> difference(p, poly_b; target), append!, polys)
+ end
+ return polys
+end
+
+#= Multipolygon with polygon difference - note that all intersection regions between
+sub-polygons of `multipoly_a` and `poly_b` will be removed from the corresponding
+sub-polygon. Unless specified with `fix_multipoly = nothing`, `multipolygon_a` will be
+validated using the given (default is `UnionIntersectingPolygons()`) correction. =#
+function _difference(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.PolygonTrait, poly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix multipoly_a to prevent returning an invalid multipolygon
+ multipoly_a = fix_multipoly(multipoly_a)
+ end
+ polys = Vector{_get_poly_type(T)}()
+ sizehint!(polys, GI.npolygon(multipoly_a))
+ for poly_a in GI.getpolygon(multipoly_a)
+ append!(polys, difference(poly_a, poly_b; target))
+ end
+ return polys
+end
+
+#= Multipolygon with multipolygon difference - note that all intersection regions between
+sub-polygons of `multipoly_a` and sub-polygons of `multipoly_b` will be removed from the
+corresponding sub-polygon of `multipoly_a`. Unless specified with `fix_multipoly = nothing`,
+`multipolygon_a` will be validated using the given (defauly is `UnionIntersectingPolygons()`)
+correction. =#
+function _difference(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix multipoly_a to prevent returning an invalid multipolygon
+ multipoly_a = fix_multipoly(multipoly_a)
+ fix_multipoly = nothing
+ end
+ local polys
+ for (i, poly_b) in enumerate(GI.getpolygon(multipoly_b))
+ polys = difference(i == 1 ? multipoly_a : GI.MultiPolygon(polys), poly_b; target, fix_multipoly)
+ end
+ return polys
+end
Many type and target combos aren't implemented
julia
function _difference(
+ ::TraitTarget{Target}, ::Type{T},
+ trait_a::GI.AbstractTrait, geom_a,
+ trait_b::GI.AbstractTrait, geom_b,
+) where {Target, T}
+ @assert(
+ false,
+ "Difference between $trait_a and $trait_b with target $Target isn't implemented yet.",
+ )
+ return nothing
+end
export intersection, intersection_points
+
+"""
+ Enum LineOrientation
+Enum for the orientation of a line with respect to a curve. A line can be
+`line_cross` (crossing over the curve), `line_hinge` (crossing the endpoint of the curve),
+`line_over` (colinear with the curve), or `line_out` (not interacting with the curve).
+"""
+@enum LineOrientation line_cross=1 line_hinge=2 line_over=3 line_out=4
+
+"""
+ intersection(geom_a, geom_b, [T::Type]; target::Type, fix_multipoly = UnionIntersectingPolygons())
+
+Return the intersection between two geometries as a list of geometries. Return an empty list
+if none are found. The type of the list will be constrained as much as possible given the
+input geometries. Furthermore, the user can provide a `target` type as a keyword argument and
+a list of target geometries found in the intersection will be returned. The user can also
+provide a float type that they would like the points of returned geometries to be. If the
+user is taking a intersection involving one or more multipolygons, and the multipolygon
+might be comprised of polygons that intersect, if `fix_multipoly` is set to an
+`IntersectingPolygons` correction (the default is `UnionIntersectingPolygons()`), then the
+needed multipolygons will be fixed to be valid before performing the intersection to ensure
+a correct answer. Only set `fix_multipoly` to nothing if you know that the multipolygons are
+valid, as it will avoid unneeded computation.
+
+# Example
+
+```jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+line1 = GI.Line([(124.584961,-12.768946), (126.738281,-17.224758)])
+line2 = GI.Line([(123.354492,-15.961329), (127.22168,-14.008696)])
+inter_points = GO.intersection(line1, line2; target = GI.PointTrait())
+GI.coordinates.(inter_points)
Helper functions for Intersections with Greiner and Hormann Polygon Clipping
julia
#= When marking the crossing status of a delayed crossing, the chain start point is bouncing
+when the start point is a entry point and is a crossing point when the start point is an
+exit point. The end of the chain has the opposite crossing / bouncing status. x is the
+entry/exit status. =#
+_inter_delay_cross_f(x) = (!x, x)
+#= When marking the crossing status of a delayed bouncing, the chain start and end points
+are crossing if the current polygon's adjacent edges are within the non-tracing polygon. If
+the edges are outside then the chain endpoints are marked as bouncing. x is a boolean
+representing if the edges are inside or outside of the polygon. =#
+_inter_delay_bounce_f(x, _) = x
+#= When tracing polygons, step forward if the most recent intersection point was an entry
+point, else step backwards where x is the entry/exit status. =#
+_inter_step(x, _) = x ? 1 : (-1)
+
+#= Polygon with multipolygon intersection - note that all intersection regions between
+`poly_a` and any of the sub-polygons of `multipoly_b` are counted as intersection polygons.
+Unless specified with `fix_multipoly = nothing`, `multipolygon_b` will be validated using
+the given (default is `UnionIntersectingPolygons()`) correction. =#
+function _intersection(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.PolygonTrait, poly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix multipoly_b to prevent duplicated intersection regions
+ multipoly_b = fix_multipoly(multipoly_b)
+ end
+ polys = Vector{_get_poly_type(T)}()
+ for poly_b in GI.getpolygon(multipoly_b)
+ append!(polys, intersection(poly_a, poly_b; target))
+ end
+ return polys
+end
+
+#= Multipolygon with polygon intersection is equivalent to taking the intersection of the
+poylgon with the multipolygon and thus simply switches the order of operations and calls the
+above method. =#
+_intersection(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.PolygonTrait, poly_b;
+ kwargs...,
+) where T = intersection(poly_b, multipoly_a; target , kwargs...)
+
+#= Multipolygon with multipolygon intersection - note that all intersection regions between
+any sub-polygons of `multipoly_a` and any of the sub-polygons of `multipoly_b` are counted
+as intersection polygons. Unless specified with `fix_multipoly = nothing`, both
+`multipolygon_a` and `multipolygon_b` will be validated using the given (default is
+`UnionIntersectingPolygons()`) correction. =#
+function _intersection(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix both multipolygons to prevent duplicated regions
+ multipoly_a = fix_multipoly(multipoly_a)
+ multipoly_b = fix_multipoly(multipoly_b)
+ fix_multipoly = nothing
+ end
+ polys = Vector{_get_poly_type(T)}()
+ for poly_a in GI.getpolygon(multipoly_a)
+ append!(polys, intersection(poly_a, multipoly_b; target, fix_multipoly))
+ end
+ return polys
+end
Many type and target combos aren't implemented
julia
function _intersection(
+ ::TraitTarget{Target}, ::Type{T},
+ trait_a::GI.AbstractTrait, geom_a,
+ trait_b::GI.AbstractTrait, geom_b;
+ kwargs...,
+) where {Target, T}
+ @assert(
+ false,
+ "Intersection between $trait_a and $trait_b with target $Target isn't implemented yet.",
+ )
+ return nothing
+end
+
+"""
+ intersection_points(
+ geom_a,
+ geom_b,
+ )::Union{
+ ::Vector{::Tuple{::Real, ::Real}},
+ ::Nothing,
+ }
+
+Return a list of intersection points between two geometries of type GI.Point.
+If no intersection point was possible given geometry extents, returns an empty
+list.
+"""
+intersection_points(geom_a, geom_b, ::Type{T} = Float64) where T <: AbstractFloat =
+ _intersection_points(T, GI.trait(geom_a), geom_a, GI.trait(geom_b), geom_b)
+
+
+#= Calculates the list of intersection points between two geometries, inlcuding line
+segments, line strings, linear rings, polygons, and multipolygons. If no intersection points
+were possible given geometry extents or if none are found, return an empty list of
+GI.Points. =#
+function _intersection_points(::Type{T}, ::GI.AbstractTrait, a, ::GI.AbstractTrait, b; exact = _False()) where T
Initialize an empty list of points
julia
result = GI.Point[]
Check if the geometries extents even overlap
julia
Extents.intersects(GI.extent(a), GI.extent(b)) || return result
Create a list of edges from the two input geometries
Loop over pairs of edges and add any intersection points to results
julia
for i in eachindex(edges_a), j in eachindex(edges_b)
+ line_orient, intr1, _ = _intersection_point(T, edges_a[i], edges_b[j]; exact)
TODO: Add in degenerate intersection points when line_over
julia
if line_orient == line_cross || line_orient == line_hinge
+ #=
+ Determine if point is on edge (all edge endpoints excluded
+ except for the last edge for an open geometry)
+ =#
+ point, (α, β) = intr1
+ on_a_edge = (!a_closed && i == npoints_a && 0 <= α <= 1) ||
+ (0 <= α < 1)
+ on_b_edge = (!b_closed && j == npoints_b && 0 <= β <= 1) ||
+ (0 <= β < 1)
+ if on_a_edge && on_b_edge
+ push!(result, GI.Point(point))
+ end
+ end
+ end
+ end
+ return result
+end
+
+#= Calculates the intersection points between two lines if they exists and the fractional
+component of each line from the initial end point to the intersection point where α is the
+fraction along (a1, a2) and β is the fraction along (b1, b2).
+
+Note that the first return is the type of intersection (line_cross, line_hinge, line_over,
+or line_out). The type of intersection determines how many intersection points there are.
+If the intersection is line_out, then there are no intersection points and the two
+intersections aren't valid and shouldn't be used. If the intersection is line_cross or
+line_hinge then the lines meet at one point and the first intersection is valid, while the
+second isn't. Finally, if the intersection is line_over, then both points are valid and they
+are the two points that define the endpoints of the overlapping region between the two
+lines.
+
+Also note again that each intersection is a tuple of two tuples. The first is the
+intersection point (x,y) while the second is the ratio along the initial lines (α, β) for
+that point.
+
+Calculation derivation can be found here: https://stackoverflow.com/questions/563198/ =#
+function _intersection_point(::Type{T}, (a1, a2)::Edge, (b1, b2)::Edge; exact) where T
Intersection is a cross if there is only one non-endpoint intersection point
julia
line_orient = line_cross
+ intr1 = _find_cross_intersection(T, a1, a2, b1, b2, a_ext, b_ext)
+ end
+ return line_orient, intr1, intr2
+end
+
+#= If lines defined by (a1, a2) and (b1, b2) are collinear, find endpoints of overlapping
+region if they exist. This could result in three possibilities. First, there could be no
+overlapping region, in which case, the default 'no_intr_result' intersection information is
+returned. Second, the two regions could just meet at one shared endpoint, in which case it
+is a hinge intersection with one intersection point. Otherwise, it is a overlapping
+intersection defined by two of the endpoints of the line segments. =#
+function _find_collinear_intersection(::Type{T}, a1, a2, b1, b2, a_ext, b_ext, no_intr_result) where T
if a1_in_b && a2_in_b # 1st vertex of a and 2nd vertex of a form overlap
+ line_orient = line_over
+ β1 = _clamped_frac(distance(a1, b1, T), b_dist)
+ β2 = _clamped_frac(distance(a2, b1, T), b_dist)
+ intr1 = (_tuple_point(a1, T), (zero(T), β1))
+ intr2 = (_tuple_point(a2, T), (one(T), β2))
+ elseif b1_in_a && b2_in_a # 1st vertex of b and 2nd vertex of b form overlap
+ line_orient = line_over
+ α1 = _clamped_frac(distance(b1, a1, T), a_dist)
+ α2 = _clamped_frac(distance(b2, a1, T), a_dist)
+ intr1 = (_tuple_point(b1, T), (α1, zero(T)))
+ intr2 = (_tuple_point(b2, T), (α2, one(T)))
+ elseif a1_in_b && b1_in_a # 1st vertex of a and 1st vertex of b form overlap
+ if equals(a1, b1)
+ line_orient = line_hinge
+ intr1 = (_tuple_point(a1, T), (zero(T), zero(T)))
+ else
+ line_orient = line_over
+ intr1, intr2 = _set_ab_collinear_intrs(T, a1, b1, zero(T), zero(T), a1, b1, a_dist, b_dist)
+ end
+ elseif a1_in_b && b2_in_a # 1st vertex of a and 2nd vertex of b form overlap
+ if equals(a1, b2)
+ line_orient = line_hinge
+ intr1 = (_tuple_point(a1, T), (zero(T), one(T)))
+ else
+ line_orient = line_over
+ intr1, intr2 = _set_ab_collinear_intrs(T, a1, b2, zero(T), one(T), a1, b1, a_dist, b_dist)
+ end
+ elseif a2_in_b && b1_in_a # 2nd vertex of a and 1st vertex of b form overlap
+ if equals(a2, b1)
+ line_orient = line_hinge
+ intr1 = (_tuple_point(a2, T), (one(T), zero(T)))
+ else
+ line_orient = line_over
+ intr1, intr2 = _set_ab_collinear_intrs(T, a2, b1, one(T), zero(T), a1, b1, a_dist, b_dist)
+ end
+ elseif a2_in_b && b2_in_a # 2nd vertex of a and 2nd vertex of b form overlap
+ if equals(a2, b2)
+ line_orient = line_hinge
+ intr1 = (_tuple_point(a2, T), (one(T), one(T)))
+ else
+ line_orient = line_over
+ intr1, intr2 = _set_ab_collinear_intrs(T, a2, b2, one(T), one(T), a1, b1, a_dist, b_dist)
+ end
+ end
+ return line_orient, intr1, intr2
+end
+
+#= Determine intersection points and segment fractions when overlap is made up one one
+endpoint of segment (a1, a2) and one endpoint of segment (b1, b2). =#
+_set_ab_collinear_intrs(::Type{T}, a_pt, b_pt, a_pt_α, b_pt_β, a1, b1, a_dist, b_dist) where T =
+ (
+ (_tuple_point(a_pt, T), (a_pt_α, _clamped_frac(distance(a_pt, b1, T), b_dist))),
+ (_tuple_point(b_pt, T), (_clamped_frac(distance(b_pt, a1, T), a_dist), b_pt_β))
+ )
+
+#= If lines defined by (a1, a2) and (b1, b2) are just touching at one of those endpoints and
+are not collinear, then they form a hinge, with just that one shared intersection point.
+Point equality is checked before segment orientation to have maximal accurary on fractions
+to avoid floating point errors. If the points are not equal, we know that the hinge does not
+take place at an endpoint and the fractions must be between 0 or 1 (exclusive). =#
+function _find_hinge_intersection(::Type{T}, a1, a2, b1, b2, a1_orient, a2_orient, b1_orient) where T
+ pt, α, β = if equals(a1, b1)
+ _tuple_point(a1, T), zero(T), zero(T)
+ elseif equals(a1, b2)
+ _tuple_point(a1, T), zero(T), one(T)
+ elseif equals(a2, b1)
+ _tuple_point(a2, T), one(T), zero(T)
+ elseif equals(a2, b2)
+ _tuple_point(a2, T), one(T), one(T)
+ elseif a1_orient == 0
+ β_val = _clamped_frac(distance(b1, a1, T), distance(b1, b2, T), eps(T))
+ _tuple_point(a1, T), zero(T), β_val
+ elseif a2_orient == 0
+ β_val = _clamped_frac(distance(b1, a2, T), distance(b1, b2, T), eps(T))
+ _tuple_point(a2, T), one(T), β_val
+ elseif b1_orient == 0
+ α_val = _clamped_frac(distance(a1, b1, T), distance(a1, a2, T), eps(T))
+ _tuple_point(b1, T), α_val, zero(T)
+ else # b2_orient == 0
+ α_val = _clamped_frac(distance(a1, b2, T), distance(a1, a2, T), eps(T))
+ _tuple_point(b2, T), α_val, one(T)
+ end
+ return pt, (α, β)
+end
+
+#= If lines defined by (a1, a2) and (b1, b2) meet at one point that is not an endpoint of
+either segment, they form a crossing intersection with a singular intersection point. That
+point is caculated by finding the fractional distance along each segment the point occurs
+at (α, β). If the point is too close to an endpoint to be distinct, the point shares a value
+with the endpoint, but with a non-zero and non-one fractional value. If the intersection
+point calculated is outside of the envelope of the two segments due to floating point error,
+it is set to the endpoint of the two segments that is closest to the other segment.
+Regardless of point value, we know that it does not actually occur at an endpoint so the
+fractions must be between 0 or 1 (exclusive). =#
+function _find_cross_intersection(::Type{T}, a1, a2, b1, b2, a_ext, b_ext) where T
Determine α value where 0 < α < 1 and β value where 0 < β < 1
julia
α = _clamped_frac(Δbax * Δby - Δbay * Δbx, a_cross_b, eps(T))
+ β = _clamped_frac(Δbax * Δay - Δbay * Δax, a_cross_b, eps(T))
+
+ #= Intersection will be where a1 + α * Δa = b1 + β * Δb. However, due to floating point
+ innacurracies, α and β calculations may yeild different intersection points. Average
+ both points together to minimize difference from real value, as long as segment isn't
+ vertical or horizontal as this will almost certianly lead to the point being outside the
+ envelope due to floating point error. Also note that floating point limitations could
+ make intersection be endpoint if α≈0 or α≈1.=#
+ x = if Δax == 0
+ a1x
+ elseif Δbx == 0
+ b1x
+ else
+ (a1x + α * Δax + b1x + β * Δbx) / 2
+ end
+ y = if Δay == 0
+ a1y
+ elseif Δby == 0
+ b1y
+ else
+ (a1y + α * Δay + b1y + β * Δby) / 2
+ end
+ pt = (x, y)
Check if point is within segment envelopes and adjust to endpoint if not
module Predicates
+ using ExactPredicates, ExactPredicates.Codegen
+ import ExactPredicates: ext
+ import ExactPredicates.Codegen: group!, @genpredicate
+ import GeometryOps: _False, _True, _booltype, _tuple_point
+ import GeoInterface as GI
+
+ #= Determine the orientation of c with regards to the oriented segment (a, b).
+ Return 1 if c is to the left of (a, b).
+ Return -1 if c is to the right of (a, b).
+ Return 0 if c is on (a, b) or if a == b. =#
+ orient(a, b, c; exact) = _orient(_booltype(exact), a, b, c)
If exact is true, use ExactPredicates to calculate the orientation.
julia
_orient(::_True, a, b, c) = ExactPredicates.orient(_tuple_point(a, Float64), _tuple_point(b, Float64), _tuple_point(c, Float64))
If exact is false, calculate the orientation without using ExactPredicates.
julia
function _orient(exact::_False, a, b, c)
+ a = a .- c
+ b = b .- c
+ return _cross(exact, a, b)
+ end
+
+ #= Determine the sign of the cross product of a and b.
+ Return 1 if the cross product is positive.
+ Return -1 if the cross product is negative.
+ Return 0 if the cross product is 0. =#
+ cross(a, b; exact) = _cross(_booltype(exact), a, b)
+
+ #= If `exact` is `true`, use exact cross product calculation created using
+ `ExactPredicates`generated predicate. Note that as of now `ExactPredicates` requires
+ Float64 so we must convert points a and b. =#
+ _cross(::_True, a, b) = _cross_exact(_tuple_point(a, Float64), _tuple_point(b, Float64))
Exact cross product calculation using ExactPredicates.
julia
@genpredicate function _cross_exact(a :: 2, b :: 2)
+ group!(a...)
+ group!(b...)
+ ext(a, b)
+ end
If exact is false, calculate the cross product without using ExactPredicates.
julia
function _cross(::_False, a, b)
+ c_t1 = GI.x(a) * GI.y(b)
+ c_t2 = GI.y(a) * GI.x(b)
+ c_val = if isapprox(c_t1, c_t2)
+ 0
+ else
+ sign(c_t1 - c_t2)
+ end
+ return c_val
+ end
+
+end
+
+import .Predicates
If we want to inject adaptivity, we would do something like:
function cross(a, b, c) # try Predicates._cross_naive(a, b, c) # check the error bound there # then try Predicates._cross_adaptive(a, b, c) # then try Predicates._cross_exact end
export union
+
+"""
+ union(geom_a, geom_b, [::Type{T}]; target::Type, fix_multipoly = UnionIntersectingPolygons())
+
+Return the union between two geometries as a list of geometries. Return an empty list if
+none are found. The type of the list will be constrained as much as possible given the input
+geometries. Furthermore, the user can provide a `taget` type as a keyword argument and a
+list of target geometries found in the difference will be returned. The user can also
+provide a float type 'T' that they would like the points of returned geometries to be. If
+the user is taking a intersection involving one or more multipolygons, and the multipolygon
+might be comprised of polygons that intersect, if `fix_multipoly` is set to an
+`IntersectingPolygons` correction (the default is `UnionIntersectingPolygons()`), then the
+needed multipolygons will be fixed to be valid before performing the intersection to ensure
+a correct answer. Only set `fix_multipoly` to false if you know that the multipolygons are
+valid, as it will avoid unneeded computation.
+
+Calculates the union between two polygons.
+# Example
+
+```jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+p1 = GI.Polygon([[(0.0, 0.0), (5.0, 5.0), (10.0, 0.0), (5.0, -5.0), (0.0, 0.0)]])
+p2 = GI.Polygon([[(3.0, 0.0), (8.0, 5.0), (13.0, 0.0), (8.0, -5.0), (3.0, 0.0)]])
+union_poly = GO.union(p1, p2; target = GI.PolygonTrait())
+GI.coordinates.(union_poly)
output
julia
1-element Vector{Vector{Vector{Vector{Float64}}}}:
+ [[[6.5, 3.5], [5.0, 5.0], [0.0, 0.0], [5.0, -5.0], [6.5, -3.5], [8.0, -5.0], [13.0, 0.0], [8.0, 5.0], [6.5, 3.5]]]
+```
+"""
+function union(
+ geom_a, geom_b, ::Type{T}=Float64; target=nothing, kwargs...
+) where {T<:AbstractFloat}
+ return _union(
+ TraitTarget(target), T, GI.trait(geom_a), geom_a, GI.trait(geom_b), geom_b;
+ exact = _True(), kwargs...,
+ )
+end
+
+#= This 'union' implementation returns the union of two polygons. The algorithm to determine
+the union was adapted from "Efficient clipping of efficient polygons," by Greiner and
+Hormann (1998). DOI: https://doi.org/10.1145/274363.274364 =#
+function _union(
+ ::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.PolygonTrait, poly_a,
+ ::GI.PolygonTrait, poly_b;
+ exact, kwargs...,
+) where T
Check if one polygon totally within other and if so, return the larger polygon
julia
a_in_b, b_in_a = false, false
+ if n_pieces == 0 # no crossing points, determine if either poly is inside the other
+ a_in_b, b_in_a = _find_non_cross_orientation(a_list, b_list, ext_a, ext_b; exact)
+ if a_in_b
+ push!(polys, GI.Polygon([tuples(ext_b)]))
+ elseif b_in_a
+ push!(polys, GI.Polygon([tuples(ext_a)]))
+ else
+ push!(polys, tuples(poly_a))
+ push!(polys, tuples(poly_b))
+ return polys
+ end
+ elseif n_pieces > 1
+ #= extra polygons are holes (n_pieces == 1 is the desired state) and since
+ holes are formed by regions exterior to both poly_a and poly_b, they can't interact
+ with pre-existing holes =#
+ sort!(polys, by = area, rev = true) # sort by area so first element is the exterior
the first element is the exterior, the rest are holes
julia
@views append!(polys[1].geom, (GI.getexterior(p) for p in polys[2:end]))
+ keepat!(polys, 1)
+ end
Add in holes
julia
if GI.nhole(poly_a) != 0 || GI.nhole(poly_b) != 0
+ _add_union_holes!(polys, a_in_b, b_in_a, poly_a, poly_b; exact)
+ end
Helper functions for Unions with Greiner and Hormann Polygon Clipping
julia
#= When marking the crossing status of a delayed crossing, the chain start point is crossing
+when the start point is a entry point and is a bouncing point when the start point is an
+exit point. The end of the chain has the opposite crossing / bouncing status. =#
+_union_delay_cross_f(x) = (x, !x)
+
+#= When marking the crossing status of a delayed bouncing, the chain start and end points
+are bouncing if the current polygon's adjacent edges are within the non-tracing polygon. If
+the edges are outside then the chain endpoints are marked as crossing. x is a boolean
+representing if the edges are inside or outside of the polygon. =#
+_union_delay_bounce_f(x, _) = !x
+
+#= When tracing polygons, step backwards if the most recent intersection point was an entry
+point, else step forwards where x is the entry/exit status. =#
+_union_step(x, _) = x ? (-1) : 1
+
+#= Add holes from two polygons to the exterior polygon formed by their union. If adding the
+the holes reveals that the polygons aren't actually intersecting, return the original
+polygons. =#
+function _add_union_holes!(polys, a_in_b, b_in_a, poly_a, poly_b; exact)
+ if a_in_b
+ _add_union_holes_contained_polys!(polys, poly_a, poly_b; exact)
+ elseif b_in_a
+ _add_union_holes_contained_polys!(polys, poly_b, poly_a; exact)
+ else # Polygons intersect, but neither is contained in the other
+ n_a_holes = GI.nhole(poly_a)
+ ext_poly_a = GI.Polygon(StaticArrays.SVector(GI.getexterior(poly_a)))
+ ext_poly_b = GI.Polygon(StaticArrays.SVector(GI.getexterior(poly_b)))
+ #= Start with poly_b when comparing with holes from poly_a and then switch to poly_a
+ to compare with holes from poly_b. For current_poly, use ext_poly_b to avoid
+ repeating overlapping holes in poly_a and poly_b =#
+ curr_exterior_poly = n_a_holes > 0 ? ext_poly_b : ext_poly_a
+ current_poly = n_a_holes > 0 ? ext_poly_b : poly_a
Loop over all holes in both original polygons
julia
for (i, ih) in enumerate(Iterators.flatten((GI.gethole(poly_a), GI.gethole(poly_b))))
+ in_ext, _, _ = _line_polygon_interactions(ih, curr_exterior_poly; exact, closed_line = true)
+ if !in_ext
+ #= if the hole isn't in the overlapping region between the two polygons, add
+ the hole to the resulting polygon as we know it can't interact with any
+ other holes =#
+ push!(polys[1].geom, ih)
+ else
+ #= if the hole is at least partially in the overlapping region, take the
+ difference of the hole from the polygon it didn't originate from - note that
+ when current_poly is poly_a this includes poly_a holes so overlapping holes
+ between poly_a and poly_b within the overlap are added, in addition to all
+ holes in non-overlapping regions =#
+ h_poly = GI.Polygon(StaticArrays.SVector(ih))
+ new_holes = difference(h_poly, current_poly; target = GI.PolygonTrait())
+ append!(polys[1].geom, (GI.getexterior(new_h) for new_h in new_holes))
+ end
+ if i == n_a_holes
+ curr_exterior_poly = ext_poly_a
+ current_poly = poly_a
+ end
+ end
+ end
+ return
+end
+
+#= Add holes holes to the union of two polygons where one of the original polygons was
+inside of the other. If adding the the holes reveal that the polygons aren't actually
+intersecting, return the original polygons.=#
+function _add_union_holes_contained_polys!(polys, interior_poly, exterior_poly; exact)
+ union_poly = polys[1]
+ ext_int_ring = GI.getexterior(interior_poly)
+ for (i, ih) in enumerate(GI.gethole(exterior_poly))
+ poly_ih = GI.Polygon(StaticArrays.SVector(ih))
+ in_ih, on_ih, out_ih = _line_polygon_interactions(ext_int_ring, poly_ih; exact, closed_line = true)
+ if in_ih # at least part of interior polygon exterior is within the ith hole
+ if !on_ih && !out_ih
+ #= interior polygon is completly within the ith hole - polygons aren't
+ touching and do not actually form a union =#
+ polys[1] = tuples(interior_poly)
+ push!(polys, tuples(exterior_poly))
+ return polys
+ else
+ #= interior polygon is partially within the ith hole - area of interior
+ polygon reduces the size of the hole =#
+ new_holes = difference(poly_ih, interior_poly; target = GI.PolygonTrait())
+ append!(union_poly.geom, (GI.getexterior(new_h) for new_h in new_holes))
+ end
+ else # none of interior polygon exterior is within the ith hole
+ if !out_ih
+ #= interior polygon's exterior is the same as the ith hole - polygons do
+ form a union, but do not overlap so all holes stay in final polygon =#
+ append!(union_poly.geom, Iterators.drop(GI.gethole(exterior_poly), i))
+ append!(union_poly.geom, GI.gethole(interior_poly))
+ return polys
+ else
+ #= interior polygon's exterior is outside of the ith hole - the interior
+ polygon could either be disjoint from the hole, or contain the hole =#
+ ext_int_poly = GI.Polygon(StaticArrays.SVector(ext_int_ring))
+ in_int, _, _ = _line_polygon_interactions(ih, ext_int_poly; exact, closed_line = true)
+ if in_int
+ #= interior polygon contains the hole - overlapping holes between the
+ interior and exterior polygons will be added =#
+ for jh in GI.gethole(interior_poly)
+ poly_jh = GI.Polygon(StaticArrays.SVector(jh))
+ if intersects(poly_ih, poly_jh)
+ new_holes = intersection(poly_ih, poly_jh; target = GI.PolygonTrait())
+ append!(union_poly.geom, (GI.getexterior(new_h) for new_h in new_holes))
+ end
+ end
+ else
+ #= interior polygon and the exterior polygon are disjoint - add the ith
+ hole as it is not covered by the interior polygon =#
+ push!(union_poly.geom, ih)
+ end
+ end
+ end
+ end
+ return
+end
+
+#= Polygon with multipolygon union - note that all sub-polygons of `multipoly_b` will be
+included, unioning these sub-polygons with `poly_a` where they intersect. Unless specified
+with `fix_multipoly = nothing`, `multipolygon_b` will be validated using the given (default
+is `UnionIntersectingPolygons()`) correction. =#
+function _union(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.PolygonTrait, poly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix multipoly_b to prevent repeated regions in the output
+ multipoly_b = fix_multipoly(multipoly_b)
+ end
+ polys = [tuples(poly_a, T)]
+ for poly_b in GI.getpolygon(multipoly_b)
+ if intersects(polys[1], poly_b)
If polygons intersect and form a new polygon, swap out polygon
julia
new_polys = union(polys[1], poly_b; target)
+ if length(new_polys) > 1 # case where they intersect by just one point
+ push!(polys, tuples(poly_b, T)) # add poly_b to list
+ else
+ polys[1] = new_polys[1]
+ end
+ else
If they don't intersect, poly_b is now a part of the union as its own polygon
julia
push!(polys, tuples(poly_b, T))
+ end
+ end
+ return polys
+end
+
+#= Multipolygon with polygon union is equivalent to taking the union of the poylgon with the
+multipolygon and thus simply switches the order of operations and calls the above method. =#
+_union(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.PolygonTrait, poly_b;
+ kwargs...,
+) where T = union(poly_b, multipoly_a; target, kwargs...)
+
+#= Multipolygon with multipolygon union - note that all of the sub-polygons of `multipoly_a`
+and the sub-polygons of `multipoly_b` are included and combined together where there are
+intersections. Unless specified with `fix_multipoly = nothing`, `multipolygon_b` will be
+validated using the given (default is `UnionIntersectingPolygons()`) correction. =#
+function _union(
+ target::TraitTarget{GI.PolygonTrait}, ::Type{T},
+ ::GI.MultiPolygonTrait, multipoly_a,
+ ::GI.MultiPolygonTrait, multipoly_b;
+ fix_multipoly = UnionIntersectingPolygons(), kwargs...,
+) where T
+ if !isnothing(fix_multipoly) # Fix multipoly_b to prevent repeated regions in the output
+ multipoly_b = fix_multipoly(multipoly_b)
+ fix_multipoly = nothing
+ end
+ multipolys = multipoly_b
+ local polys
+ for poly_a in GI.getpolygon(multipoly_a)
+ polys = union(poly_a, multipolys; target, fix_multipoly)
+ multipolys = GI.MultiPolygon(polys)
+ end
+ return polys
+end
Many type and target combos aren't implemented
julia
function _union(
+ ::TraitTarget{Target}, ::Type{T},
+ trait_a::GI.AbstractTrait, geom_a,
+ trait_b::GI.AbstractTrait, geom_b;
+ kwargs...
+) where {Target,T}
+ throw(ArgumentError("Union between $trait_a and $trait_b with target $Target isn't implemented yet."))
+ return nothing
+end
Distance is the distance of a point to another geometry. This is always a positive number. If a point is inside of geometry, so on a curve or inside of a polygon, the distance will be zero. Signed distance is mainly used for polygons and multipolygons. If a point is outside of a geometry, signed distance has the same value as distance. However, points within the geometry have a negative distance representing the distance of a point to the closest boundary. Therefore, for all "non-filled" geometries, like curves, the distance will either be postitive or 0.
To provide an example, consider this rectangle:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+rect = GI.Polygon([[(0,0), (0,1), (1,1), (1,0), (0, 0)]])
+point_in = (0.5, 0.5)
+point_out = (0.5, 1.5)
+f, a, p = poly(collect(GI.getpoint(rect)); axis = (; aspect = DataAspect()))
+scatter!(GI.x(point_in), GI.y(point_in); color = :red)
+scatter!(GI.x(point_out), GI.y(point_out); color = :orange)
+f
This is clearly a rectangle with one point inside and one point outside. The points are both an equal distance to the polygon. The distance to point_in is negative while the distance to point_out is positive.
This is the GeoInterface-compatible implementation. First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Distance and signed distance are only implemented for points to other geometries right now. This could be extended to include distance from other geometries in the future.
The distance calculated is the Euclidean distance using the Pythagorean theorem. Also note that singed_distance only makes sense for "filled-in" shapes, like polygons, so it isn't implemented for curves.
julia
const _DISTANCE_TARGETS = TraitTarget{Union{GI.AbstractPolygonTrait,GI.LineStringTrait,GI.LinearRingTrait,GI.LineTrait,GI.PointTrait}}()
+
+"""
+ distance(point, geom, ::Type{T} = Float64)::T
+
+Calculates the ditance from the geometry `g1` to the `point`. The distance
+will always be positive or zero.
+
+The method will differ based on the type of the geometry provided:
+ - The distance from a point to a point is just the Euclidean distance
+ between the points.
+ - The distance from a point to a line is the minimum distance from the point
+ to the closest point on the given line.
+ - The distance from a point to a linestring is the minimum distance from the
+ point to the closest segment of the linestring.
+ - The distance from a point to a linear ring is the minimum distance from
+ the point to the closest segment of the linear ring.
+ - The distance from a point to a polygon is zero if the point is within the
+ polygon and otherwise is the minimum distance from the point to an edge of
+ the polygon. This includes edges created by holes.
+ - The distance from a point to a multigeometry or a geometry collection is
+ the minimum distance between the point and any of the sub-geometries.
+
+Result will be of type T, where T is an optional argument with a default value
+of Float64.
+"""
+function distance(
+ geom1, geom2, ::Type{T} = Float64; threaded=false
+) where T<:AbstractFloat
+ distance(GI.trait(geom1), geom1, GI.trait(geom2), geom2, T; threaded)
+end
+function distance(
+ trait1, geom, trait2::GI.PointTrait, point, ::Type{T} = Float64;
+ threaded=false
+) where T<:AbstractFloat
+ distance(trait2, point, trait1, geom, T) # Swap order
+end
+function distance(
+ trait1::GI.PointTrait, point, trait2, geom, ::Type{T} = Float64;
+ threaded=false
+) where T<:AbstractFloat
+ applyreduce(min, _DISTANCE_TARGETS, geom; threaded, init=typemax(T)) do g
+ _distance(T, trait1, point, GI.trait(g), g)
+ end
+end
_distance(::Type{T}, ::GI.PointTrait, point, ::GI.PointTrait, geom) where T =
+ _euclid_distance(T, point, geom)
+_distance(::Type{T}, ::GI.PointTrait, point, ::GI.LineTrait, geom) where T =
+ _distance_line(T, point, GI.getpoint(geom, 1), GI.getpoint(geom, 2))
+_distance(::Type{T}, ::GI.PointTrait, point, ::GI.LineStringTrait, geom) where T =
+ _distance_curve(T, point, geom; close_curve = false)
+_distance(::Type{T}, ::GI.PointTrait, point, ::GI.LinearRingTrait, geom) where T =
+ _distance_curve(T, point, geom; close_curve = true)
Point-Polygon
julia
function _distance(::Type{T}, ::GI.PointTrait, point, ::GI.PolygonTrait, geom) where T
+ within(point, geom) && return zero(T)
+ return _distance_polygon(T, point, geom)
+end
+
+"""
+ signed_distance(point, geom, ::Type{T} = Float64)::T
+
+Calculates the signed distance from the geometry `geom` to the given point.
+Points within `geom` have a negative signed distance, and points outside of
+`geom` have a positive signed distance.
+ - The signed distance from a point to a point, line, linestring, or linear
+ ring is equal to the distance between the two.
+ - The signed distance from a point to a polygon is negative if the point is
+ within the polygon and is positive otherwise. The value of the distance is
+ the minimum distance from the point to an edge of the polygon. This includes
+ edges created by holes.
+ - The signed distance from a point to a multigeometry or a geometry
+ collection is the minimum signed distance between the point and any of the
+ sub-geometries.
+
+Result will be of type T, where T is an optional argument with a default value
+of Float64.
+"""
+function signed_distance(
+ geom1, geom2, ::Type{T} = Float64; threaded=false
+) where T<:AbstractFloat
+ signed_distance(GI.trait(geom1), geom1, GI.trait(geom2), geom2, T; threaded)
+end
+function signed_distance(
+ trait1, geom, trait2::GI.PointTrait, point, ::Type{T} = Float64;
+ threaded=false
+) where T<:AbstractFloat
+ signed_distance(trait2, point, trait1, geom, T; threaded) # Swap order
+end
+function signed_distance(
+ trait1::GI.PointTrait, point, trait2, geom, ::Type{T} = Float64;
+ threaded=false
+) where T<:AbstractFloat
+ applyreduce(min, _DISTANCE_TARGETS, geom; threaded, init=typemax(T)) do g
+ _signed_distance(T, trait1, point, GI.trait(g), g)
+ end
+end
function _signed_distance(
+ ::Type{T}, ptrait::GI.PointTrait, point, gtrait::GI.AbstractGeometryTrait, geom
+) where T
+ _distance(T, ptrait, point, gtrait, geom)
+end
Point-Polygon
julia
function _signed_distance(::Type{T}, ::GI.PointTrait, point, ::GI.PolygonTrait, geom) where T
+ min_dist = _distance_polygon(T, point, geom)
+ return within(point, geom) ? -min_dist : min_dist
negative if point is inside polygon
julia
end
Returns the Euclidean distance between two points.
julia
Base.@propagate_inbounds _euclid_distance(::Type{T}, p1, p2) where T =
+ sqrt(_squared_euclid_distance(T, p1, p2))
Returns the square of the euclidean distance between two points
julia
Base.@propagate_inbounds _squared_euclid_distance(::Type{T}, p1, p2) where T =
+ _squared_euclid_distance(
+ T,
+ GeoInterface.x(p1), GeoInterface.y(p1),
+ GeoInterface.x(p2), GeoInterface.y(p2),
+ )
Returns the Euclidean distance between two points given their x and y values.
julia
Base.@propagate_inbounds _euclid_distance(::Type{T}, x1, y1, x2, y2) where T =
+ sqrt(_squared_euclid_distance(T, x1, y1, x2, y2))
Returns the squared Euclidean distance between two points given their x and y values.
julia
Base.@propagate_inbounds _squared_euclid_distance(::Type{T}, x1, y1, x2, y2) where T =
+ T((x2 - x1)^2 + (y2 - y1)^2)
Returns the minimum distance from point p0 to the line defined by endpoints p1 and p2.
julia
_distance_line(::Type{T}, p0, p1, p2) where T =
+ sqrt(_squared_distance_line(T, p0, p1, p2))
Returns the squared minimum distance from point p0 to the line defined by endpoints p1 and p2.
julia
function _squared_distance_line(::Type{T}, p0, p1, p2) where T
+ x0, y0 = GeoInterface.x(p0), GeoInterface.y(p0)
+ x1, y1 = GeoInterface.x(p1), GeoInterface.y(p1)
+ x2, y2 = GeoInterface.x(p2), GeoInterface.y(p2)
+
+ xfirst, yfirst, xlast, ylast = x1 < x2 ? (x1, y1, x2, y2) : (x2, y2, x1, y1)
+
+ #=
+ Vectors from first point to last point (v) and from first point to point of
+ interest (w) to find the projection of w onto v to find closest point
+ =#
+ v = (xlast - xfirst, ylast - yfirst)
+ w = (x0 - xfirst, y0 - yfirst)
+
+ c1 = sum(w .* v)
+ if c1 <= 0 # p0 is closest to first endpoint
+ return _squared_euclid_distance(T, x0, y0, xfirst, yfirst)
+ end
+
+ c2 = sum(v .* v)
+ if c2 <= c1 # p0 is closest to last endpoint
+ return _squared_euclid_distance(T, x0, y0, xlast, ylast)
+ end
+
+ b2 = c1 / c2 # projection fraction
+ return _squared_euclid_distance(T, x0, y0, xfirst + (b2 * v[1]), yfirst + (b2 * v[2]))
+end
Returns the minimum distance from the given point to the given curve. If close_curve is true, make sure to include the edge from the first to last point of the curve, even if it isn't explicitly repeated.
julia
function _distance_curve(::Type{T}, point, curve; close_curve = false) where T
see if linear ring has explicitly repeated last point in coordinates
Returns the minimum distance from the given point to an edge of the given polygon, including from edges created by holes. Assumes polygon isn't filled and treats the exterior and each hole as a linear ring.
julia
function _distance_polygon(::Type{T}, point, poly) where T
+ min_dist = _distance_curve(T, point, GI.getexterior(poly); close_curve = true)
+ @inbounds for hole in GI.gethole(poly)
+ dist = _distance_curve(T, point, hole; close_curve = true)
+ min_dist = dist < min_dist ? dist : min_dist
+ end
+ return min_dist
+end
The equals function checks if two geometries are equal. They are equal if they share the same set of points and edges to define the same shape.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.LineString([(0.0, 0.0), (0.0, 10.0)])
+l2 = GI.LineString([(0.0, -10.0), (0.0, 3.0)])
+f, a, p = lines(GI.getpoint(l1), color = :blue)
+scatter!(GI.getpoint(l1), color = :blue)
+lines!(GI.getpoint(l2), color = :orange)
+scatter!(GI.getpoint(l2), color = :orange)
+f
We can see that the two lines do not share a commen set of points and edges in the plot, so they are not equal:
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Note that while we need the same set of points and edges, they don't need to be provided in the same order for polygons. For for example, we need the same set points for two multipoints to be equal, but they don't have to be saved in the same order. The winding order also doesn't have to be the same to represent the same geometry. This requires checking every point against every other point in the two geometries we are comparing. Also, some geometries must be "closed" like polygons and linear rings. These will be assumed to be closed, even if they don't have a repeated last point explicity written in the coordinates. Additionally, geometries and multi-geometries can be equal if the multi-geometry only includes that single geometry.
julia
"""
+ equals(geom1, geom2)::Bool
+
+Compare two Geometries return true if they are the same geometry.
+
+# Examples
+```jldoctest
+import GeometryOps as GO, GeoInterface as GI
+poly1 = GI.Polygon([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+poly2 = GI.Polygon([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+
+GO.equals(poly1, poly2)
output
julia
true
+```
+"""
+equals(geom_a, geom_b) = equals(
+ GI.trait(geom_a), geom_a,
+ GI.trait(geom_b), geom_b,
+)
+
+"""
+ equals(::T, geom_a, ::T, geom_b)::Bool
+
+Two geometries of the same type, which don't have a equals function to dispatch
+off of should throw an error.
+"""
+equals(::T, geom_a, ::T, geom_b) where T = error("Cant compare $T yet")
+
+"""
+ equals(trait_a, geom_a, trait_b, geom_b)
+
+Two geometries which are not of the same type cannot be equal so they always
+return false.
+"""
+equals(trait_a, geom_a, trait_b, geom_b) = false
+
+"""
+ equals(::GI.PointTrait, p1, ::GI.PointTrait, p2)::Bool
+
+Two points are the same if they have the same x and y (and z if 3D) coordinates.
+"""
+function equals(::GI.PointTrait, p1, ::GI.PointTrait, p2)
+ GI.ncoord(p1) == GI.ncoord(p2) || return false
+ GI.x(p1) == GI.x(p2) || return false
+ GI.y(p1) == GI.y(p2) || return false
+ if GI.is3d(p1)
+ GI.z(p1) == GI.z(p2) || return false
+ end
+ return true
+end
+
+"""
+ equals(::GI.PointTrait, p1, ::GI.MultiPointTrait, mp2)::Bool
+
+A point and a multipoint are equal if the multipoint is composed of a single
+point that is equivalent to the given point.
+"""
+function equals(::GI.PointTrait, p1, ::GI.MultiPointTrait, mp2)
+ GI.npoint(mp2) == 1 || return false
+ return equals(p1, GI.getpoint(mp2, 1))
+end
+
+"""
+ equals(::GI.MultiPointTrait, mp1, ::GI.PointTrait, p2)::Bool
+
+A point and a multipoint are equal if the multipoint is composed of a single
+point that is equivalent to the given point.
+"""
+equals(trait1::GI.MultiPointTrait, mp1, trait2::GI.PointTrait, p2) =
+ equals(trait2, p2, trait1, mp1)
+
+"""
+ equals(::GI.MultiPointTrait, mp1, ::GI.MultiPointTrait, mp2)::Bool
+
+Two multipoints are equal if they share the same set of points.
+"""
+function equals(::GI.MultiPointTrait, mp1, ::GI.MultiPointTrait, mp2)
+ GI.npoint(mp1) == GI.npoint(mp2) || return false
+ for p1 in GI.getpoint(mp1)
+ has_match = false # if point has a matching point in other multipoint
+ for p2 in GI.getpoint(mp2)
+ if equals(p1, p2)
+ has_match = true
+ break
+ end
+ end
+ has_match || return false # if no matching point, can't be equal
+ end
+ return true # all points had a match
+end
+
+"""
+ _equals_curves(c1, c2, closed_type1, closed_type2)::Bool
+
+Two curves are equal if they share the same set of point, representing the same
+geometry. Both curves must must be composed of the same set of points, however,
+they do not have to wind in the same direction, or start on the same point to be
+equivalent.
+Inputs:
+ c1 first geometry
+ c2 second geometry
+ closed_type1::Bool true if c1 is closed by definition (polygon, linear ring)
+ closed_type2::Bool true if c2 is closed by definition (polygon, linear ring)
+"""
+function _equals_curves(c1, c2, closed_type1, closed_type2)
Check all remaining points are the same wrapping around line
julia
jstep = same_direction ? 1 : -1
+ for i in 2:n1
+ ip = GI.getpoint(c1, i)
+ j = jstart + (i - 1) * jstep
+ j += (0 < j <= n2) ? 0 : (n2 * -jstep)
+ jp = GI.getpoint(c2, j)
+ equals(ip, jp) || return false
+ end
+ return true
+end
+
+"""
+ equals(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l2,
+ )::Bool
+
+Two lines/linestrings are equal if they share the same set of points going
+along the curve. Note that lines/linestrings aren't closed by defintion.
+"""
+equals(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l2,
+) = _equals_curves(l1, l2, false, false)
+
+"""
+ equals(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l1,
+ ::GI.LinearRingTrait, l2,
+ )::Bool
+
+A line/linestring and a linear ring are equal if they share the same set of
+points going along the curve. Note that lines aren't closed by defintion, but
+rings are, so the line must have a repeated last point to be equal
+"""
+equals(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l1,
+ ::GI.LinearRingTrait, l2,
+) = _equals_curves(l1, l2, false, true)
+
+"""
+ equals(
+ ::GI.LinearRingTrait, l1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l2,
+ )::Bool
+
+A linear ring and a line/linestring are equal if they share the same set of
+points going along the curve. Note that lines aren't closed by defintion, but
+rings are, so the line must have a repeated last point to be equal
+"""
+equals(
+ ::GI.LinearRingTrait, l1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, l2,
+) = _equals_curves(l1, l2, true, false)
+
+"""
+ equals(
+ ::GI.LinearRingTrait, l1,
+ ::GI.LinearRingTrait, l2,
+ )::Bool
+
+Two linear rings are equal if they share the same set of points going along the
+curve. Note that rings are closed by definition, so they can have, but don't
+need, a repeated last point to be equal.
+"""
+equals(
+ ::GI.LinearRingTrait, l1,
+ ::GI.LinearRingTrait, l2,
+) = _equals_curves(l1, l2, true, true)
+
+"""
+ equals(::GI.PolygonTrait, geom_a, ::GI.PolygonTrait, geom_b)::Bool
+
+Two polygons are equal if they share the same exterior edge and holes.
+"""
+function equals(::GI.PolygonTrait, geom_a, ::GI.PolygonTrait, geom_b)
Check if exterior is equal
julia
_equals_curves(
+ GI.getexterior(geom_a), GI.getexterior(geom_b),
+ true, true, # linear rings are closed by definition
+ ) || return false
for ihole in GI.gethole(geom_a)
+ has_match = false
+ for jhole in GI.gethole(geom_b)
+ if _equals_curves(
+ ihole, jhole,
+ true, true, # linear rings are closed by definition
+ )
+ has_match = true
+ break
+ end
+ end
+ has_match || return false
+ end
+ return true
+end
+
+"""
+ equals(::GI.PolygonTrait, geom_a, ::GI.MultiPolygonTrait, geom_b)::Bool
+
+A polygon and a multipolygon are equal if the multipolygon is composed of a
+single polygon that is equivalent to the given polygon.
+"""
+function equals(::GI.PolygonTrait, geom_a, ::MultiPolygonTrait, geom_b)
+ GI.npolygon(geom_b) == 1 || return false
+ return equals(geom_a, GI.getpolygon(geom_b, 1))
+end
+
+"""
+ equals(::GI.MultiPolygonTrait, geom_a, ::GI.PolygonTrait, geom_b)::Bool
+
+A polygon and a multipolygon are equal if the multipolygon is composed of a
+single polygon that is equivalent to the given polygon.
+"""
+equals(trait_a::GI.MultiPolygonTrait, geom_a, trait_b::PolygonTrait, geom_b) =
+ equals(trait_b, geom_b, trait_a, geom_a)
+
+"""
+ equals(::GI.PolygonTrait, geom_a, ::GI.PolygonTrait, geom_b)::Bool
+
+Two multipolygons are equal if they share the same set of polygons.
+"""
+function equals(::GI.MultiPolygonTrait, geom_a, ::GI.MultiPolygonTrait, geom_b)
for poly_a in GI.getpolygon(geom_a)
+ has_match = false
+ for poly_b in GI.getpolygon(geom_b)
+ if equals(poly_a, poly_b)
+ has_match = true
+ break
+ end
+ end
+ has_match || return false
+ end
+ return true
+end
The contains function checks if a given geometry completly contains another geometry, or in other words, that the second geometry is completly within the first. This requires that the two interiors intersect and that the interior and boundary of the second geometry is not in the exterior of the first geometry.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.LineString([(0.0, 0.0), (1.0, 0.0), (0.0, 0.1)])
+l2 = GI.LineString([(0.25, 0.0), (0.75, 0.0)])
+f, a, p = lines(GI.getpoint(l1), color = :blue)
+scatter!(GI.getpoint(l1), color = :blue)
+lines!(GI.getpoint(l2), color = :orange)
+scatter!(GI.getpoint(l2), color = :orange)
+f
We can see that all of the points and edges of l2 are within l1, so l1 contains l2. However, l2 does not contain l1.
This is the GeoInterface-compatible implementation.
Given that contains is the exact opposite of within, we simply pass the two inputs variables, swapped in order, to within.
julia
"""
+ contains(g1::AbstractGeometry, g2::AbstractGeometry)::Bool
+
+Return true if the second geometry is completely contained by the first
+geometry. The interiors of both geometries must intersect and the interior and
+boundary of the secondary (g2) must not intersect the exterior of the first
+(g1).
+
+`contains` returns the exact opposite result of `within`.
+
+# Examples
+
+```jldoctest
+import GeometryOps as GO, GeoInterface as GI
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = GI.Point((1, 2))
+
+GO.contains(line, point)
The coveredby function checks if one geometry is covered by another geometry. This is an extension of within that does not require the interiors of the two geometries to intersect, but still does require that the interior and boundary of the first geometry isn't outside of the second geometry.
To provide an example, consider this point and line:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+p1 = (0.0, 0.0)
+l1 = GI.Line([p1, (1.0, 1.0)])
+f, a, p = lines(GI.getpoint(l1))
+scatter!(p1, color = :red)
+f
As we can see, p1 is on the endpoint of l1. This means it is not within, but it does meet the definition of coveredby.
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait.
Each of these calls a method in the geom_geom_processors file. The methods in this file determine if the given geometries meet a set of criteria. For the coveredby function and arguments g1 and g2, this criteria is as follows: - points of g1 are allowed to be in the interior of g2 (either through overlap or crossing for lines) - points of g1 are allowed to be on the boundary of g2 - points of g1 are not allowed to be in the exterior of g2 - no points of g1 are required to be in the interior of g2 - no points of g1 are required to be on the boundary of g2 - no points of g1 are required to be in the exterior of g2
The code for the specific implementations is in the geom_geom_processors file.
julia
const COVEREDBY_ALLOWS = (in_allow = true, on_allow = true, out_allow = false)
+const COVEREDBY_CURVE_ALLOWS = (over_allow = true, cross_allow = true, on_allow = true, out_allow = false)
+const COVEREDBY_CURVE_REQUIRES = (in_require = false, on_require = false, out_require = false)
+const COVEREDBY_POLYGON_REQUIRES = (in_require = true, on_require = false, out_require = false,)
+const COVEREDBY_EXACT = (exact = _False(),)
+
+"""
+ coveredby(g1, g2)::Bool
+
+Return `true` if the first geometry is completely covered by the second
+geometry. The interior and boundary of the primary geometry (g1) must not
+intersect the exterior of the secondary geometry (g2).
+
+Furthermore, `coveredby` returns the exact opposite result of `covers`. They are
+equivalent with the order of the arguments swapped.
+
+# Examples
+```jldoctest setup=:(using GeometryOps, GeometryBasics)
+import GeometryOps as GO, GeoInterface as GI
+p1 = GI.Point(0.0, 0.0)
+p2 = GI.Point(1.0, 1.0)
+l1 = GI.Line([p1, p2])
+
+GO.coveredby(p1, l1)
#= Linestring is coveredby a line if all interior and boundary points of the
+first line are on the interior/boundary points of the second line. =#
+_coveredby(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ COVEREDBY_CURVE_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = false,
+ closed_curve = false,
+)
+
+#= Linestring is coveredby a ring if all interior and boundary points of the
+line are on the edges of the ring. =#
+_coveredby(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ COVEREDBY_CURVE_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = false,
+ closed_curve = true,
+)
+
+#= Linestring is coveredby a polygon if all interior and boundary points of the
+line are in the polygon interior or on its edges, inlcuding hole edges. =#
+_coveredby(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ COVEREDBY_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = false,
+)
#= Linearring is covered by a line if all vertices and edges of the ring are on
+the edges and vertices of the line. =#
+_coveredby(
+ ::GI.LinearRingTrait, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ COVEREDBY_CURVE_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = true,
+ closed_curve = false,
+)
+
+#= Linearring is covered by another linear ring if all vertices and edges of the
+first ring are on the edges/vertices of the second ring. =#
+_coveredby(
+ ::GI.LinearRingTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ COVEREDBY_CURVE_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = true,
+ closed_curve = true,
+)
+
+#= Linearring is coveredby a polygon if all vertices and edges of the ring are
+in the polygon interior or on the polygon edges, inlcuding hole edges. =#
+_coveredby(
+ ::GI.LinearRingTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ COVEREDBY_ALLOWS...,
+ COVEREDBY_CURVE_REQUIRES...,
+ COVEREDBY_EXACT...,
+ closed_line = true,
+)
#= Polygon is covered by another polygon if if the interior and edges of the
+first polygon are in the second polygon interior or on polygon edges, including
+hole edges.=#
+_coveredby(
+ ::GI.PolygonTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _polygon_polygon_process(
+ g1, g2;
+ COVEREDBY_ALLOWS...,
+ COVEREDBY_POLYGON_REQUIRES...,
+ COVEREDBY_EXACT...,
+)
#= Geometry is covered by a multi-geometry or a collection if one of the elements
+of the collection cover the geometry. =#
+function _coveredby(
+ ::Union{GI.PointTrait, GI.AbstractCurveTrait, GI.PolygonTrait}, g1,
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g2,
+)
+ for sub_g2 in GI.getgeom(g2)
+ coveredby(g1, sub_g2) && return true
+ end
+ return false
+end
#= Multi-geometry or a geometry collection is covered by a geometry if all
+elements of the collection are covered by the geometry. =#
+function _coveredby(
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g1,
+ ::GI.AbstractGeometryTrait, g2,
+)
+ for sub_g1 in GI.getgeom(g1)
+ !coveredby(sub_g1, g2) && return false
+ end
+ return true
+end
The covers function checks if a given geometry completly covers another geometry. For this to be true, the "contained" geometry's interior and boundaries must be covered by the "covering" geometry's interior and boundaries. The interiors do not need to overlap.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+p1 = (0.0, 0.0)
+p2 = (1.0, 1.0)
+l1 = GI.Line([p1, p2])
+
+f, a, p = lines(GI.getpoint(l1))
+scatter!(p1, color = :red)
+f
This is the GeoInterface-compatible implementation.
Given that covers is the exact opposite of coveredby, we simply pass the two inputs variables, swapped in order, to coveredby.
julia
"""
+ covers(g1::AbstractGeometry, g2::AbstractGeometry)::Bool
+
+Return true if the first geometry is completely covers the second geometry,
+The exterior and boundary of the second geometry must not be outside of the
+interior and boundary of the first geometry. However, the interiors need not
+intersect.
+
+`covers` returns the exact opposite result of `coveredby`.
+
+# Examples
+
+```jldoctest
+import GeometryOps as GO, GeoInterface as GI
+l1 = GI.LineString([(1.0, 1.0), (1.0, 2.0), (1.0, 3.0), (1.0, 4.0)])
+l2 = GI.LineString([(1.0, 1.0), (1.0, 2.0)])
+
+GO.covers(l1, l2)
"""
+ crosses(geom1, geom2)::Bool
+
+Return `true` if the intersection results in a geometry whose dimension is one less than
+the maximum dimension of the two source geometries and the intersection set is interior to
+both source geometries.
+
+TODO: broken
+
+# Examples
+```julia
+import GeoInterface as GI, GeometryOps as GO
TODO: Add working example
julia
```
+"""
+crosses(g1, g2)::Bool = crosses(trait(g1), g1, trait(g2), g2)::Bool
+crosses(t1::FeatureTrait, g1, t2, g2)::Bool = crosses(GI.geometry(g1), g2)
+crosses(t1, g1, t2::FeatureTrait, g2)::Bool = crosses(g1, geometry(g2))
+crosses(::MultiPointTrait, g1, ::LineStringTrait, g2)::Bool = multipoint_crosses_line(g1, g2)
+crosses(::MultiPointTrait, g1, ::PolygonTrait, g2)::Bool = multipoint_crosses_poly(g1, g2)
+crosses(::LineStringTrait, g1, ::MultiPointTrait, g2)::Bool = multipoint_crosses_lines(g2, g1)
+crosses(::LineStringTrait, g1, ::PolygonTrait, g2)::Bool = line_crosses_poly(g1, g2)
+crosses(::LineStringTrait, g1, ::LineStringTrait, g2)::Bool = line_crosses_line(g1, g2)
+crosses(::PolygonTrait, g1, ::MultiPointTrait, g2)::Bool = multipoint_crosses_poly(g2, g1)
+crosses(::PolygonTrait, g1, ::LineStringTrait, g2)::Bool = line_crosses_poly(g2, g1)
+
+function multipoint_crosses_line(geom1, geom2)
+ int_point = false
+ ext_point = false
+ i = 1
+ np2 = GI.npoint(geom2)
+
+ while i < GI.npoint(geom1) && !int_point && !ext_point
+ for j in 1:GI.npoint(geom2) - 1
+ exclude_boundary = (j === 1 || j === np2 - 2) ? :none : :both
+ if _point_on_segment(GI.getpoint(geom1, i), (GI.getpoint(geom2, j), GI.getpoint(geom2, j + 1)); exclude_boundary)
+ int_point = true
+ else
+ ext_point = true
+ end
+ end
+ i += 1
+ end
+ return int_point && ext_point
+end
+
+function line_crosses_line(line1, line2)
+ np2 = GI.npoint(line2)
+ if GeometryOps.intersects(line1, line2)
+ for i in 1:GI.npoint(line1) - 1
+ for j in 1:GI.npoint(line2) - 1
+ exclude_boundary = (j === 1 || j === np2 - 2) ? :none : :both
+ pa = GI.getpoint(line1, i)
+ pb = GI.getpoint(line1, i + 1)
+ p = GI.getpoint(line2, j)
+ _point_on_segment(p, (pa, pb); exclude_boundary) && return true
+ end
+ end
+ end
+ return false
+end
+
+function line_crosses_poly(line, poly)
+ for l in flatten(AbstractCurveTrait, poly)
+ intersects(line, l) && return true
+ end
+ return false
+end
+
+function multipoint_crosses_poly(mp, poly)
+ int_point = false
+ ext_point = false
+
+ for p in GI.getpoint(mp)
+ if _point_polygon_process(
+ p, poly;
+ in_allow = true, on_allow = true, out_allow = false, exact = _False()
+ )
+ int_point = true
+ else
+ ext_point = true
+ end
+ int_point && ext_point && return true
+ end
+ return false
+end
+
+#= TODO: Once crosses is swapped over to use the geom relations workflow, can
+delete these helpers. =#
+
+function _point_on_segment(point, (start, stop); exclude_boundary::Symbol=:none)::Bool
+ x, y = GI.x(point), GI.y(point)
+ x1, y1 = GI.x(start), GI.y(start)
+ x2, y2 = GI.x(stop), GI.y(stop)
+
+ dxc = x - x1
+ dyc = y - y1
+ dx1 = x2 - x1
+ dy1 = y2 - y1
The disjoint function checks if one geometry is outside of another geometry, without sharing any boundaries or interiors.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.LineString([(0.0, 0.0), (1.0, 0.0), (0.0, 0.1)])
+l2 = GI.LineString([(2.0, 0.0), (2.75, 0.0)])
+f, a, p = lines(GI.getpoint(l1), color = :blue)
+scatter!(GI.getpoint(l1), color = :blue)
+lines!(GI.getpoint(l2), color = :orange)
+scatter!(GI.getpoint(l2), color = :orange)
+f
We can see that none of the edges or vertices of l1 interact with l2 so they are disjoint.
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait.
Each of these calls a method in the geom_geom_processors file. The methods in this file determine if the given geometries meet a set of criteria. For the disjoint function and arguments g1 and g2, this criteria is as follows: - points of g1 are not allowed to be in the interior of g2 - points of g1 are not allowed to be on the boundary of g2 - points of g1 are allowed to be in the exterior of g2 - no points required to be in the interior of g2 - no points of g1 are required to be on the boundary of g2 - no points of g1 are required to be in the exterior of g2
The code for the specific implementations is in the geom_geom_processors file.
julia
const DISJOINT_ALLOWS = (in_allow = false, on_allow = false, out_allow = true)
+const DISJOINT_CURVE_ALLOWS = (over_allow = false, cross_allow = false, on_allow = false, out_allow = true)
+const DISJOINT_REQUIRES = (in_require = false, on_require = false, out_require = false)
+const DISJOINT_EXACT = (exact = _False(),)
+
+"""
+ disjoint(geom1, geom2)::Bool
+
+Return `true` if the first geometry is disjoint from the second geometry.
+
+Return `true` if the first geometry is disjoint from the second geometry. The
+interiors and boundaries of both geometries must not intersect.
+
+# Examples
+```jldoctest setup=:(using GeometryOps, GeoInterface)
+import GeometryOps as GO, GeoInterface as GI
+
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = (2, 2)
+GO.disjoint(point, line)
Point is disjoint from a linearring if it is not on the ring's edges/vertices.
julia
_disjoint(
+ ::GI.PointTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = _point_curve_process(
+ g1, g2;
+ DISJOINT_ALLOWS...,
+ closed_curve = true,
+)
+
+#= Point is disjoint from a polygon if it is not on any edges, vertices, or
+within the polygon's interior. =#
+_disjoint(
+ ::GI.PointTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _point_polygon_process(
+ g1, g2;
+ DISJOINT_ALLOWS...,
+ DISJOINT_EXACT...,
+)
+
+#= Geometry is disjoint from a point if the point is not in the interior or on
+the boundary of the geometry. =#
+_disjoint(
+ trait1::Union{GI.AbstractCurveTrait, GI.PolygonTrait}, g1,
+ trait2::GI.PointTrait, g2,
+) = _disjoint(trait2, g2, trait1, g1)
#= Linestring is disjoint from another line if they do not share any interior
+edge/vertex points or boundary points. =#
+_disjoint(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ DISJOINT_CURVE_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+ closed_line = false,
+ closed_curve = false,
+)
+
+#= Linestring is disjoint from a linearring if they do not share any interior
+edge/vertex points or boundary points. =#
+_disjoint(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ DISJOINT_CURVE_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+ closed_line = false,
+ closed_curve = true,
+)
+
+#= Linestring is disjoint from a polygon if the interior and boundary points of
+the line are not in the polygon's interior or on the polygon's boundary. =#
+_disjoint(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ DISJOINT_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+ closed_line = false,
+)
+
+#= Geometry is disjoint from a linestring if the line's interior and boundary
+points don't intersect with the geometrie's interior and boundary points. =#
+_disjoint(
+ trait1::Union{GI.LinearRingTrait, GI.PolygonTrait}, g1,
+ trait2::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _disjoint(trait2, g2, trait1, g1)
#= Linearrings is disjoint from another linearring if they do not share any
+interior edge/vertex points or boundary points.=#
+_disjoint(
+ ::GI.LinearRingTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ DISJOINT_CURVE_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+ closed_line = true,
+ closed_curve = true,
+)
+
+#= Linearring is disjoint from a polygon if the interior and boundary points of
+the ring are not in the polygon's interior or on the polygon's boundary. =#
+_disjoint(
+ ::GI.LinearRingTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ DISJOINT_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+ closed_line = true,
+)
#= Polygon is disjoint from another polygon if they do not share any edges or
+vertices and if their interiors do not intersect, excluding any holes. =#
+_disjoint(
+ ::GI.PolygonTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _polygon_polygon_process(
+ g1, g2;
+ DISJOINT_ALLOWS...,
+ DISJOINT_REQUIRES...,
+ DISJOINT_EXACT...,
+)
#= Geometry is disjoint from a multi-geometry or a collection if all of the
+elements of the collection are disjoint from the geometry. =#
+function _disjoint(
+ ::Union{GI.PointTrait, GI.AbstractCurveTrait, GI.PolygonTrait}, g1,
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g2,
+)
+ for sub_g2 in GI.getgeom(g2)
+ !disjoint(g1, sub_g2) && return false
+ end
+ return true
+end
#= Multi-geometry or a geometry collection is covered by a geometry if all
+elements of the collection are covered by the geometry. =#
+function _disjoint(
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g1,
+ ::GI.AbstractGeometryTrait, g2,
+)
+ for sub_g1 in GI.getgeom(g1)
+ !disjoint(sub_g1, g2) && return false
+ end
+ return true
+end
#= Code is based off of DE-9IM Standards (https://en.wikipedia.org/wiki/DE-9IM)
+and attempts a standardized solution for most of the functions.
+=#
+
+"""
+ Enum PointOrientation
+
+Enum for the orientation of a point with respect to a curve. A point can be
+`point_in` the curve, `point_on` the curve, or `point_out` of the curve.
+"""
+@enum PointOrientation point_in=1 point_on=2 point_out=3
Determines if a point meets the given checks with respect to a curve.
If in_allow is true, the point can be on the curve interior. If on_allow is true, the point can be on the curve boundary. If out_allow is true, the point can be disjoint from the curve.
If the point is in an "allowed" location, return true. Else, return false.
If closed_curve is true, curve is treated as a closed curve where the first and last point are connected by a segment.
julia
function _point_curve_process(
+ point, curve;
+ in_allow, on_allow, out_allow,
+ closed_curve = false,
+)
p_start = GI.getpoint(curve, closed_curve ? n : 1)
+ @inbounds for i in (closed_curve ? 1 : 2):n
+ p_end = GI.getpoint(curve, i)
+ seg_val = _point_segment_orientation(point, p_start, p_end)
+ seg_val == point_in && return in_allow
+ if seg_val == point_on
+ if !closed_curve # if point is on curve endpoints, it is "on"
+ i == 2 && equals(point, p_start) && return on_allow
+ i == n && equals(point, p_end) && return on_allow
+ end
+ return in_allow
+ end
+ p_start = p_end
+ end
+ return out_allow
+end
Determines if a point meets the given checks with respect to a polygon.
If in_allow is true, the point can be within the polygon interior If on_allow is true, the point can be on the polygon boundary. If out_allow is true, the point can be disjoint from the polygon.
If the point is in an "allowed" location, return true. Else, return false.
julia
function _point_polygon_process(
+ point, polygon;
+ in_allow, on_allow, out_allow, exact,
+)
Check interaction of geom with polygon's exterior boundary
If a point is outside, it isn't interacting with any holes
julia
ext_val == point_out && return out_allow
if a point is on an external boundary, it isn't interacting with any holes
julia
ext_val == point_on && return on_allow
If geom is within the polygon, need to check interactions with holes
julia
for hole in GI.gethole(polygon)
+ hole_val = _point_filled_curve_orientation(point, hole; exact)
If a point in in a hole, it is outside of the polygon
julia
hole_val == point_in && return out_allow
If a point in on a hole edge, it is on the edge of the polygon
julia
hole_val == point_on && return on_allow
+ end
Point is within external boundary and on in/on any holes
julia
return in_allow
+end
Determines if a line meets the given checks with respect to a curve.
If over_allow is true, segments of the line and curve can be co-linear. If cross_allow is true, segments of the line and curve can cross. If on_allow is true, endpoints of either the line or curve can intersect a segment of the other geometry. If cross_allow is true, segments of the line and curve can be disjoint.
If in_require is true, the interiors of the line and curve must meet in at least one point. If on_require is true, the bounday of one of the two geometries can meet the interior or boundary of the other geometry in at least one point. If out_require is true, there must be at least one point of the given line that is exterior of the curve.
If the point is in an "allowed" location and meets all requirments, return true. Else, return false.
If closed_line is true, line is treated as a closed line where the first and last point are connected by a segment. Same with closed_curve.
Find next pieces of hinge to see if line and curve cross
julia
l, c = _find_hinge_next_segments(
+ α, β, l_start, l_end, c_start, c_end,
+ i, line, j, curve,
+ )
+ next_val, _, _ = _intersection_point(Float64, l, c; exact)
+ if next_val == line_hinge
+ !cross_allow && return false
+ else
+ !over_allow && return false
+ end
+ end
+ end
+ end
no overlap for a give segment, some of segment must be out of curve
julia
if j == nc
+ !out_allow && return false
+ out_req_met = true
+ end
+ end
+ c_start = c_end # consider next segment of curve
+ if j == nc # move on to next line segment
+ i += 1
+ l_start = l_end
+ end
+ end
+ end
+ return in_req_met && on_req_met && out_req_met
+end
+
+#= If entire segment (le to ls) isn't covered by segment (cs to ce), find remaining section
+part of section outside of cs to ce. If completly covered, increase segment index i. =#
+function _find_new_seg(i, ls, le, cs, ce)
+ break_off = true
+ if _point_segment_orientation(le, cs, ce) != point_out
+ ls = le
+ i += 1
+ elseif !equals(ls, cs) && _point_segment_orientation(cs, ls, le) != point_out
+ ls = cs
+ elseif !equals(ls, ce) && _point_segment_orientation(ce, ls, le) != point_out
+ ls = ce
+ else
+ break_off = false
+ end
+ return i, ls, break_off
+end
+
+#= Find next set of segments needed to determine if given hinge segments cross or not.=#
+function _find_hinge_next_segments(α, β, ls, le, cs, ce, i, line, j, curve)
+ next_seg = if β == 1
+ if α == 1 # hinge at endpoints, so next segment of both is needed
+ ((le, _tuple_point(GI.getpoint(line, i + 1))), (ce, _tuple_point(GI.getpoint(curve, j + 1))))
+ else # hinge at curve endpoint and line interior point, curve next segment needed
+ ((ls, le), (ce, _tuple_point(GI.getpoint(curve, j + 1))))
+ end
+ else # hinge at curve interior point and line endpoint, line next segment needed
+ ((le, _tuple_point(GI.getpoint(line, i + 1))), (cs, ce))
+ end
+ return next_seg
+end
Determines if a line meets the given checks with respect to a polygon.
If in_allow is true, segments of the line can be in the polygon interior. If on_allow is true, segments of the line can be on the polygon's boundary. If out_allow is true, segments of the line can be outside of the polygon.
If in_require is true, the interiors of the line and polygon must meet in at least one point. If on_require is true, the line must have at least one point on the polygon'same boundary. If out_require is true, the line must have at least one point outside of the polygon.
If the point is in an "allowed" location and meets all requirments, return true. Else, return false.
If closed_line is true, line is treated as a closed line where the first and last point are connected by a segment.
for hole in GI.gethole(polygon)
+ in_hole, on_hole, out_hole =_line_filled_curve_interactions(
+ line, hole;
+ exact, closed_line = closed_line,
+ )
+ if in_hole # line in hole is equivalent to being out of polygon
+ !out_allow && return false
+ out_req_met = true
+ end
+ if on_hole # hole bounday is polygon boundary
+ !on_allow && return false
+ on_req_met = true
+ end
+ if !out_hole # entire line is in/on hole, can't be in/on other holes
+ in_curve = false
+ break
+ end
+ end
+ if in_curve # entirely of curve isn't within a hole
+ !in_allow && return false
+ in_req_met = true
+ end
+ return in_req_met && on_req_met && out_req_met
+end
Determines if a polygon meets the given checks with respect to a polygon.
If in_allow is true, the polygon's interiors must intersect. If on_allow is true, the one of the polygon's boundaries must either interact with the other polygon's boundary or interior. If out_allow is true, the first polygon must have interior regions outside of the second polygon.
If in_require is true, the polygon interiors must meet in at least one point. If on_require is true, one of the polygon's must have at least one boundary point in or on the other polygon. If out_require is true, the first polygon must have at least one interior point outside of the second polygon.
If the point is in an "allowed" location and meets all requirments, return true. Else, return false.
!e2_out_h1 && return in_req_met && on_req_met && out_req_met
+ break
+ end
+ end
+ #=
+ poly2 isn't outside of poly1 and isn't in a hole, poly1 interior must
+ interact with poly2 interior
+ =#
+ !in_allow && return false
+ in_req_met = true
If any of poly2 holes are within poly1, part of poly1 is exterior to poly2
julia
for h2 in GI.gethole(poly2)
+ h2_in_p1, h2_on_p1, _ = _line_polygon_interactions(
+ h2, poly1;
+ exact, closed_line = true,
+ )
+ if h2_on_p1
+ !on_allow && return false
+ on_req_met = true
+ end
+ if h2_in_p1
+ !out_allow && return false
+ out_req_met = true
+ end
+ end
+ return in_req_met && on_req_met && out_req_met
+end
Determines if a point is in, on, or out of a segment. If the point is on the segment it is on one of the segments endpoints. If it is in, it is on any other point of the segment. If the point is not on any part of the segment, it is out of the segment.
Point should be an object of point trait and curve should be an object with a linestring or linearring trait.
Can provide values of in, on, and out keywords, which determines return values for each scenario.
julia
function _point_segment_orientation(
+ point, start, stop;
+ in::T = point_in, on::T = point_on, out::T = point_out,
+) where {T}
If point is equal to the segment start or end points
julia
return on
+ else
+ #=
+ Determine if the point is on the segment -> see if vector from segment
+ start to point is parallel to segment and if point is between the
+ segment endpoints
+ =#
+ on_line = _isparallel(Δx_seg, Δy_seg, Δx_pt, Δy_pt)
+ !on_line && return out
+ between_endpoints =
+ (x2 > x1 ? x1 <= x <= x2 : x2 <= x <= x1) &&
+ (y2 > y1 ? y1 <= y <= y2 : y2 <= y <= y1)
+ !between_endpoints && return out
+ end
+ return in
+end
Determine if point is in, on, or out of a closed curve, which includes the space enclosed by the closed curve.
In means the point is within the closed curve (excluding edges and vertices). On means the point is on an edge or a vertex of the closed curve. Out means the point is outside of the closed curve.
Point should be an object of point trait and curve should be an object with a linestring or linearring trait, that is assumed to be closed, regardless of repeated last point.
Can provide values of in, on, and out keywords, which determines return values for each scenario.
Note that this uses the Algorithm by Hao and Sun (2018): https://doi.org/10.3390/sym10100477 Paper seperates orientation of point and edge into 26 cases. For each case, it is either a case where the point is on the edge (returns on), where a ray from the point (x, y) to infinity along the line y = y cut through the edge (k += 1), or the ray does not pass through the edge (do nothing and continue). If the ray passes through an odd number of edges, it is within the curve, else outside of of the curve if it didn't return 'on'. See paper for more information on cases denoted in comments.
julia
function _point_filled_curve_orientation(
+ point, curve;
+ in::T = point_in, on::T = point_on, out::T = point_out, exact,
+) where {T}
+ x, y = GI.x(point), GI.y(point)
+ n = GI.npoint(curve)
+ n -= equals(GI.getpoint(curve, 1), GI.getpoint(curve, n)) ? 1 : 0
+ k = 0 # counter for ray crossings
+ p_start = GI.getpoint(curve, n)
+ for (i, p_end) in enumerate(GI.getpoint(curve))
+ i > n && break
+ v1 = GI.y(p_start) - y
+ v2 = GI.y(p_end) - y
+ if !((v1 < 0 && v2 < 0) || (v1 > 0 && v2 > 0)) # if not cases 11 or 26
+ u1, u2 = GI.x(p_start) - x, GI.x(p_end) - x
+ f = Predicates.cross((u1, u2), (v1, v2); exact)
+ if v2 > 0 && v1 ≤ 0 # Case 3, 9, 16, 21, 13, or 24
+ f == 0 && return on # Case 16 or 21
+ f > 0 && (k += 1) # Case 3 or 9
+ elseif v1 > 0 && v2 ≤ 0 # Case 4, 10, 19, 20, 12, or 25
+ f == 0 && return on # Case 19 or 20
+ f < 0 && (k += 1) # Case 4 or 10
+ elseif v2 == 0 && v1 < 0 # Case 7, 14, or 17
+ f == 0 && return on # Case 17
+ elseif v1 == 0 && v2 < 0 # Case 8, 15, or 18
+ f == 0 && return on # Case 18
+ elseif v1 == 0 && v2 == 0 # Case 1, 2, 5, 6, 22, or 23
+ u2 ≤ 0 && u1 ≥ 0 && return on # Case 1
+ u1 ≤ 0 && u2 ≥ 0 && return on # Case 2
+ end
+ end
+ p_start = p_end
+ end
+ return iseven(k) ? out : in
+end
Determines the types of interactions of a line with a filled-in curve. By filled-in curve, I am referring to the exterior ring of a poylgon, for example.
Returns a tuple of booleans: (in_curve, on_curve, out_curve).
If in_curve is true, some of the lines interior points interact with the curve's interior points. If on_curve is true, endpoints of either the line intersect with the curve or the line interacts with the polygon boundary. If out_curve is true, at least one segments of the line is outside the curve.
If closed_line is true, line is treated as a closed line where the first and last point are connected by a segment.
If line and curve meet, then at least one point is on boundary
julia
on_curve = true
+ if seg_val == line_cross
When crossing boundary, line is both in and out of curve
julia
in_curve = true
+ out_curve = true
+ else
+ if seg_val == line_over
+ sp = _point_segment_orientation(l_start, c_start, c_end)
+ lp = _point_segment_orientation(l_end, c_start, c_end)
+ if sp != point_in || lp != point_in
+ #=
+ Line crosses over segment endpoint, creating a hinge
+ with another segment.
+ =#
+ seg_val = line_hinge
+ end
+ end
+ if seg_val == line_hinge
+ #=
+ Can't determine all types of interactions (in, out) with
+ hinge as it could pass through multiple other segments
+ so calculate if segment endpoints and intersections are
+ in/out of filled curve
+ =#
+ ipoints = intersection_points(GI.Line(StaticArrays.SVector(l_start, l_end)), curve)
+ npoints = length(ipoints) # since hinge, at least one
+ dist_from_lstart = let l_start = l_start
+ x -> _euclid_distance(Float64, x, l_start)
+ end
+ sort!(ipoints, by = dist_from_lstart)
+ p_start = _tuple_point(l_start)
+ for i in 1:(npoints + 1)
+ p_end = i ≤ npoints ? _tuple_point(ipoints[i]) : l_end
+ mid_val = _point_filled_curve_orientation((p_start .+ p_end) ./ 2, curve; exact)
+ if mid_val == point_in
+ in_curve = true
+ elseif mid_val == point_out
+ out_curve = true
+ end
+ end
already checked segment against whole filled curve
julia
l_start = l_end
+ break
+ end
+ end
+ end
+ c_start = c_end
+ end
+ l_start = l_end
+ end
+ return in_curve, on_curve, out_curve
+end
Determines the types of interactions of a line with a polygon.
Returns a tuple of booleans: (in_poly, on_poly, out_poly).
If in_poly is true, some of the lines interior points interact with the polygon interior points. If in_poly is true, endpoints of either the line intersect with the polygon or the line interacts with the polygon boundary, including hole bounaries. If out_curve is true, at least one segments of the line is outside the polygon, including inside of holes.
If closed_line is true, line is treated as a closed line where the first and last point are connected by a segment.
The intersects function checks if a given geometry intersects with another geometry, or in other words, the either the interiors or boundaries of the two geometries intersect.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+line1 = GI.Line([(124.584961,-12.768946), (126.738281,-17.224758)])
+line2 = GI.Line([(123.354492,-15.961329), (127.22168,-14.008696)])
+f, a, p = lines(GI.getpoint(line1))
+lines!(GI.getpoint(line2))
+f
We can see that they intersect, so we expect intersects to return true, and we can visualize the intersection point in red.
This is the GeoInterface-compatible implementation.
Given that intersects is the exact opposite of disjoint, we simply pass the two inputs variables, swapped in order, to disjoint.
julia
"""
+ intersects(geom1, geom2)::Bool
+
+Return true if the interiors or boundaries of the two geometries interact.
+
+`intersects` returns the exact opposite result of `disjoint`.
+
+# Example
+
+```jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+line1 = GI.Line([(124.584961,-12.768946), (126.738281,-17.224758)])
+line2 = GI.Line([(123.354492,-15.961329), (127.22168,-14.008696)])
+GO.intersects(line1, line2)
The overlaps function checks if two geometries overlap. Two geometries can only overlap if they have the same dimension, and if they overlap, but one is not contained, within, or equal to the other.
Note that this means it is impossible for a single point to overlap with a single point and a line only overlaps with another line if only a section of each line is colinear.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.LineString([(0.0, 0.0), (0.0, 10.0)])
+l2 = GI.LineString([(0.0, -10.0), (0.0, 3.0)])
+f, a, p = lines(GI.getpoint(l1), color = :blue)
+scatter!(GI.getpoint(l1), color = :blue)
+lines!(GI.getpoint(l2), color = :orange)
+scatter!(GI.getpoint(l2), color = :orange)
+f
We can see that the two lines overlap in the plot:
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait. This is also used in the implementation, since it's a lot less work!
Note that that since only elements of the same dimension can overlap, any two geometries with traits that are of different dimensions autmoatically can return false.
For geometries with the same trait dimension, we must make sure that they share a point, an edge, or area for points, lines, and polygons/multipolygons respectivly, without being contained.
julia
"""
+ overlaps(geom1, geom2)::Bool
+
+Compare two Geometries of the same dimension and return true if their
+intersection set results in a geometry different from both but of the same
+dimension. This means one geometry cannot be within or contain the other and
+they cannot be equal
+
+# Examples
+```jldoctest
+import GeometryOps as GO, GeoInterface as GI
+poly1 = GI.Polygon([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+poly2 = GI.Polygon([[(1,1), (1,6), (6,6), (6,1), (1,1)]])
+
+GO.overlaps(poly1, poly2)
output
julia
true
+```
+"""
+overlaps(geom1, geom2)::Bool = overlaps(
+ GI.trait(geom1),
+ geom1,
+ GI.trait(geom2),
+ geom2,
+)
+
+"""
+ overlaps(::GI.AbstractTrait, geom1, ::GI.AbstractTrait, geom2)::Bool
+
+For any non-specified pair, all have non-matching dimensions, return false.
+"""
+overlaps(::GI.AbstractTrait, geom1, ::GI.AbstractTrait, geom2) = false
+
+"""
+ overlaps(
+ ::GI.MultiPointTrait, points1,
+ ::GI.MultiPointTrait, points2,
+ )::Bool
+
+If the multipoints overlap, meaning some, but not all, of the points within the
+multipoints are shared, return true.
+"""
+function overlaps(
+ ::GI.MultiPointTrait, points1,
+ ::GI.MultiPointTrait, points2,
+)
+ one_diff = false # assume that all the points are the same
+ one_same = false # assume that all points are different
+ for p1 in GI.getpoint(points1)
+ match_point = false
+ for p2 in GI.getpoint(points2)
+ if equals(p1, p2) # Point is shared
+ one_same = true
+ match_point = true
+ break
+ end
+ end
+ one_diff |= !match_point # Point isn't shared
+ one_same && one_diff && return true
+ end
+ return false
+end
+
+"""
+ overlaps(::GI.LineTrait, line1, ::GI.LineTrait, line)::Bool
+
+If the lines overlap, meaning that they are colinear but each have one endpoint
+outside of the other line, return true. Else false.
+"""
+overlaps(::GI.LineTrait, line1, ::GI.LineTrait, line) =
+ _overlaps((a1, a2), (b1, b2))
+
+"""
+ overlaps(
+ ::Union{GI.LineStringTrait, GI.LinearRing}, line1,
+ ::Union{GI.LineStringTrait, GI.LinearRing}, line2,
+ )::Bool
+
+If the curves overlap, meaning that at least one edge of each curve overlaps,
+return true. Else false.
+"""
+function overlaps(
+ ::Union{GI.LineStringTrait, GI.LinearRing}, line1,
+ ::Union{GI.LineStringTrait, GI.LinearRing}, line2,
+)
+ edges_a, edges_b = map(sort! ∘ to_edges, (line1, line2))
+ for edge_a in edges_a
+ for edge_b in edges_b
+ _overlaps(edge_a, edge_b) && return true
+ end
+ end
+ return false
+end
+
+"""
+ overlaps(
+ trait_a::GI.PolygonTrait, poly_a,
+ trait_b::GI.PolygonTrait, poly_b,
+ )::Bool
+
+If the two polygons intersect with one another, but are not equal, return true.
+Else false.
+"""
+function overlaps(
+ trait_a::GI.PolygonTrait, poly_a,
+ trait_b::GI.PolygonTrait, poly_b,
+)
+ edges_a, edges_b = map(sort! ∘ to_edges, (poly_a, poly_b))
+ return _line_intersects(edges_a, edges_b) &&
+ !equals(trait_a, poly_a, trait_b, poly_b)
+end
+
+"""
+ overlaps(
+ ::GI.PolygonTrait, poly1,
+ ::GI.MultiPolygonTrait, polys2,
+ )::Bool
+
+Return true if polygon overlaps with at least one of the polygons within the
+multipolygon. Else false.
+"""
+function overlaps(
+ ::GI.PolygonTrait, poly1,
+ ::GI.MultiPolygonTrait, polys2,
+)
+ for poly2 in GI.getgeom(polys2)
+ overlaps(poly1, poly2) && return true
+ end
+ return false
+end
+
+"""
+ overlaps(
+ ::GI.MultiPolygonTrait, polys1,
+ ::GI.PolygonTrait, poly2,
+ )::Bool
+
+Return true if polygon overlaps with at least one of the polygons within the
+multipolygon. Else false.
+"""
+overlaps(trait1::GI.MultiPolygonTrait, polys1, trait2::GI.PolygonTrait, poly2) =
+ overlaps(trait2, poly2, trait1, polys1)
+
+"""
+ overlaps(
+ ::GI.MultiPolygonTrait, polys1,
+ ::GI.MultiPolygonTrait, polys2,
+ )::Bool
+
+Return true if at least one pair of polygons from multipolygons overlap. Else
+false.
+"""
+function overlaps(
+ ::GI.MultiPolygonTrait, polys1,
+ ::GI.MultiPolygonTrait, polys2,
+)
+ for poly1 in GI.getgeom(polys1)
+ overlaps(poly1, polys2) && return true
+ end
+ return false
+end
+
+#= If the edges overlap, meaning that they are colinear but each have one endpoint
+outside of the other edge, return true. Else false. =#
+function _overlaps(
+ (a1, a2)::Edge,
+ (b1, b2)::Edge,
+ exact = _False(),
+)
cross = (x - x1) * Δyl - (y - y1) * Δxl
+ if cross == 0 # point is on line extending to infinity
is line between endpoints
julia
if abs(Δxl) >= abs(Δyl) # is line between endpoints
+ return Δxl > 0 ? x1 <= x <= x2 : x2 <= x <= x1
+ else
+ return Δyl > 0 ? y1 <= y <= y2 : y2 <= y <= y1
+ end
+ end
+ return false
+end
+
+#= Returns true if there is at least one intersection between edges within the
+two lists of edges. =#
+function _line_intersects(
+ edges_a::Vector{<:Edge},
+ edges_b::Vector{<:Edge};
+)
The touches function checks if one geometry touches another geometry. In other words, the interiors of the two geometries don't interact, but one of the geometries must have a boundary point that interacts with either the other geometies interior or boundary.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.Line([(0.0, 0.0), (1.0, 0.0)])
+l2 = GI.Line([(1.0, 0.0), (1.0, -1.0)])
+
+f, a, p = lines(GI.getpoint(l1))
+lines!(GI.getpoint(l2))
+f
We can see that these two lines touch only at their endpoints.
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait.
Each of these calls a method in the geom_geom_processors file. The methods in this file determine if the given geometries meet a set of criteria. For the touches function and arguments g1 and g2, this criteria is as follows: - points of g1 are not allowed to be in the interior of g2 - points of g1 are allowed to be on the boundary of g2 - points of g1 are allowed to be in the exterior of g2 - no points of g1 are required to be in the interior of g2 - at least one point of g1 is required to be on the boundary of g2 - no points of g1 are required to be in the exterior of g2
The code for the specific implementations is in the geom_geom_processors file.
julia
const TOUCHES_POINT_ALLOWED = (in_allow = false, on_allow = true, out_allow = false)
+const TOUCHES_CURVE_ALLOWED = (over_allow = false, cross_allow = false, on_allow = true, out_allow = true)
+const TOUCHES_POLYGON_ALLOWS = (in_allow = false, on_allow = true, out_allow = true)
+const TOUCHES_REQUIRES = (in_require = false, on_require = true, out_require = false)
+const TOUCHES_EXACT = (exact = _False(),)
+
+"""
+ touches(geom1, geom2)::Bool
+
+Return `true` if the first geometry touches the second geometry. In other words,
+the two interiors cannot interact, but one of the geometries must have a
+boundary point that interacts with either the other geometies interior or
+boundary.
+
+# Examples
+```jldoctest setup=:(using GeometryOps, GeometryBasics)
+import GeometryOps as GO, GeoInterface as GI
+
+l1 = GI.Line([(0.0, 0.0), (1.0, 0.0)])
+l2 = GI.Line([(1.0, 1.0), (1.0, -1.0)])
+
+GO.touches(l1, l2)
#= Linestring touches another line if at least one bounday point interacts with
+the bounday of interior of the other line, but the interiors don't interact. =#
+_touches(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ TOUCHES_CURVE_ALLOWED...,
+ TOUCHES_REQUIRES...,
+ TOUCHES_EXACT...,
+ closed_line = false,
+ closed_curve = false,
+)
+
+
+#= Linestring touches a linearring if at least one of the boundary points of the
+line interacts with the linear ring, but their interiors can't interact. =#
+_touches(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ TOUCHES_CURVE_ALLOWED...,
+ TOUCHES_REQUIRES...,
+ TOUCHES_EXACT...,
+ closed_line = false,
+ closed_curve = true,
+)
+
+#= Linestring touches a polygon if at least one of the boundary points of the
+line interacts with the boundary of the polygon. =#
+_touches(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ TOUCHES_POLYGON_ALLOWS...,
+ TOUCHES_REQUIRES...,
+ TOUCHES_EXACT...,
+ closed_line = false,
+)
#= Linearring touches a linestring if at least one of the boundary points of the
+line interacts with the linear ring, but their interiors can't interact. =#
+_touches(
+ trait1::GI.LinearRingTrait, g1,
+ trait2::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _touches(trait2, g2, trait1, g1)
+
+#= Linearring cannot touch another linear ring since they are both exclusively
+made up of interior points and no bounday points =#
+_touches(
+ ::GI.LinearRingTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = false
+
+#= Linearring touches a polygon if at least one of the points of the ring
+interact with the polygon bounday and non are in the polygon interior. =#
+_touches(
+ ::GI.LinearRingTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ TOUCHES_POLYGON_ALLOWS...,
+ TOUCHES_REQUIRES...,
+ TOUCHES_EXACT...,
+ closed_line = true,
+)
#= Polygon touches a curve if at least one of the curve bounday points interacts
+with the polygon's bounday and no curve points interact with the interior.=#
+_touches(
+ trait1::GI.PolygonTrait, g1,
+ trait2::GI.AbstractCurveTrait, g2
+) = _touches(trait2, g2, trait1, g1)
+
+
+#= Polygon touches another polygon if they share at least one boundary point and
+no interior points. =#
+_touches(
+ ::GI.PolygonTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _polygon_polygon_process(
+ g1, g2;
+ TOUCHES_POLYGON_ALLOWS...,
+ TOUCHES_REQUIRES...,
+ TOUCHES_EXACT...,
+)
#= Geometry touch a multi-geometry or a collection if the geometry touches at
+least one of the elements of the collection. =#
+function _touches(
+ ::Union{GI.PointTrait, GI.AbstractCurveTrait, GI.PolygonTrait}, g1,
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g2,
+)
+ for sub_g2 in GI.getgeom(g2)
+ !touches(g1, sub_g2) && return false
+ end
+ return true
+end
#= Multi-geometry or a geometry collection touches a geometry if at least one
+elements of the collection touches the geometry. =#
+function _touches(
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g1,
+ ::GI.AbstractGeometryTrait, g2,
+)
+ for sub_g1 in GI.getgeom(g1)
+ !touches(sub_g1, g2) && return false
+ end
+ return true
+end
The within function checks if one geometry is inside another geometry. This requires that the two interiors intersect and that the interior and boundary of the first geometry is not in the exterior of the second geometry.
To provide an example, consider these two lines:
julia
import GeometryOps as GO
+import GeoInterface as GI
+using Makie
+using CairoMakie
+
+l1 = GI.LineString([(0.0, 0.0), (1.0, 0.0), (0.0, 0.1)])
+l2 = GI.LineString([(0.25, 0.0), (0.75, 0.0)])
+f, a, p = lines(GI.getpoint(l1), color = :blue)
+scatter!(GI.getpoint(l1), color = :blue)
+lines!(GI.getpoint(l2), color = :orange)
+scatter!(GI.getpoint(l2), color = :orange)
+f
We can see that all of the points and edges of l2 are within l1, so l2 is within l1, but l1 is not within l2
This is the GeoInterface-compatible implementation.
First, we implement a wrapper method that dispatches to the correct implementation based on the geometry trait.
Each of these calls a method in the geom_geom_processors file. The methods in this file determine if the given geometries meet a set of criteria. For the within function and arguments g1 and g2, this criteria is as follows: - points of g1 are allowed to be in the interior of g2 (either through overlap or crossing for lines) - points of g1 are allowed to be on the boundary of g2 - points of g1 are not allowed to be in the exterior of g2 - at least one point of g1 is required to be in the interior of g2 - no points of g1 are required to be on the boundary of g2 - no points of g1 are required to be in the exterior of g2
The code for the specific implementations is in the geom_geom_processors file.
julia
const WITHIN_POINT_ALLOWS = (in_allow = true, on_allow = false, out_allow = false)
+const WITHIN_CURVE_ALLOWS = (over_allow = true, cross_allow = true, on_allow = true, out_allow = false)
+const WITHIN_POLYGON_ALLOWS = (in_allow = true, on_allow = true, out_allow = false)
+const WITHIN_REQUIRES = (in_require = true, on_require = false, out_require = false)
+const WITHIN_EXACT = (exact = _False(),)
+
+"""
+ within(geom1, geom2)::Bool
+
+Return `true` if the first geometry is completely within the second geometry.
+The interiors of both geometries must intersect and the interior and boundary of
+the primary geometry (geom1) must not intersect the exterior of the secondary
+geometry (geom2).
+
+Furthermore, `within` returns the exact opposite result of `contains`.
+
+# Examples
+```jldoctest setup=:(using GeometryOps, GeometryBasics)
+import GeometryOps as GO, GeoInterface as GI
+
+line = GI.LineString([(1, 1), (1, 2), (1, 3), (1, 4)])
+point = (1, 2)
+GO.within(point, line)
Point is within another point if those points are equal.
julia
_within(
+ ::GI.PointTrait, g1,
+ ::GI.PointTrait, g2,
+) = equals(g1, g2)
+
+#= Point is within a linestring if it is on a vertex or an edge of that line,
+excluding the start and end vertex if the line is not closed. =#
+_within(
+ ::GI.PointTrait, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _point_curve_process(
+ g1, g2;
+ WITHIN_POINT_ALLOWS...,
+ closed_curve = false,
+)
Point is within a linearring if it is on a vertex or an edge of that ring.
julia
_within(
+ ::GI.PointTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = _point_curve_process(
+ g1, g2;
+ WITHIN_POINT_ALLOWS...,
+ closed_curve = true,
+)
+
+#= Point is within a polygon if it is inside of that polygon, excluding edges,
+vertices, and holes. =#
+_within(
+ ::GI.PointTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _point_polygon_process(
+ g1, g2;
+ WITHIN_POINT_ALLOWS...,
+ WITHIN_EXACT...,
+)
No geometries other than points can be within points
#= Linestring is within another linestring if their interiors intersect and no
+points of the first line are in the exterior of the second line. =#
+_within(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ WITHIN_CURVE_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = false,
+ closed_curve = false,
+)
+
+#= Linestring is within a linear ring if their interiors intersect and no points
+of the line are in the exterior of the ring. =#
+_within(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ WITHIN_CURVE_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = false,
+ closed_curve = true,
+)
+
+#= Linestring is within a polygon if their interiors intersect and no points of
+the line are in the exterior of the polygon, although they can be on an edge. =#
+_within(
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ WITHIN_POLYGON_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = false,
+)
#= Linearring is within a linestring if their interiors intersect and no points
+of the ring are in the exterior of the line. =#
+_within(
+ ::GI.LinearRingTrait, g1,
+ ::Union{GI.LineTrait, GI.LineStringTrait}, g2,
+) = _line_curve_process(
+ g1, g2;
+ WITHIN_CURVE_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = true,
+ closed_curve = false,
+)
+
+#= Linearring is within another linearring if their interiors intersect and no
+points of the first ring are in the exterior of the second ring. =#
+_within(
+ ::GI.LinearRingTrait, g1,
+ ::GI.LinearRingTrait, g2,
+) = _line_curve_process(
+ g1, g2;
+ WITHIN_CURVE_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = true,
+ closed_curve = true,
+)
+
+#= Linearring is within a polygon if their interiors intersect and no points of
+the ring are in the exterior of the polygon, although they can be on an edge. =#
+_within(
+ ::GI.LinearRingTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _line_polygon_process(
+ g1, g2;
+ WITHIN_POLYGON_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+ closed_line = true,
+)
#= Polygon is within another polygon if the interior of the first polygon
+intersects with the interior of the second and no points of the first polygon
+are outside of the second polygon. =#
+_within(
+ ::GI.PolygonTrait, g1,
+ ::GI.PolygonTrait, g2,
+) = _polygon_polygon_process(
+ g1, g2;
+ WITHIN_POLYGON_ALLOWS...,
+ WITHIN_REQUIRES...,
+ WITHIN_EXACT...,
+)
Geometries within multi-geometry/geometry collections
julia
#= Geometry is within a multi-geometry or a collection if the geometry is within
+at least one of the collection elements. =#
+function _within(
+ ::Union{GI.PointTrait, GI.AbstractCurveTrait, GI.PolygonTrait}, g1,
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g2,
+)
+ for sub_g2 in GI.getgeom(g2)
+ within(g1, sub_g2) && return true
+ end
+ return false
+end
Multi-geometry/geometry collections within geometries
julia
#= Multi-geometry or a geometry collection is within a geometry if all
+elements of the collection are within the geometry. =#
+function _within(
+ ::Union{
+ GI.MultiPointTrait, GI.AbstractMultiCurveTrait,
+ GI.MultiPolygonTrait, GI.GeometryCollectionTrait,
+ }, g1,
+ ::GI.AbstractGeometryTrait, g2,
+)
+ for sub_g1 in GI.getgeom(g1)
+ !within(sub_g1, g2) && return false
+ end
+ return true
+end
A polygon is concave if it has at least one interior angle greater than 180 degrees, meaning that the interior of the polygon is not a convex set.
These are all adapted from Turf.jl.
The may not necessarily be what want in the end but work for now!
julia
"""
+ isclockwise(line::Union{LineString, Vector{Position}})::Bool
+
+Take a ring and return true or false whether or not the ring is clockwise or
+counter-clockwise.
+
+# Example
+
+```jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+ring = GI.LinearRing([(0, 0), (1, 1), (1, 0), (0, 0)])
+GO.isclockwise(ring)
output
julia
true
+```
+"""
+isclockwise(geom)::Bool = isclockwise(GI.trait(geom), geom)
+
+function isclockwise(::AbstractCurveTrait, line)::Bool
+ sum = 0.0
+ prev = GI.getpoint(line, 1)
+ for p in GI.getpoint(line)
sum will be zero for the first point as x is subtracted from itself
julia
sum += (GI.x(p) - GI.x(prev)) * (GI.y(p) + GI.y(prev))
+ prev = p
+ end
+
+ return sum > 0.0
+end
+
+"""
+ isconcave(poly::Polygon)::Bool
+
+Take a polygon and return true or false as to whether it is concave or not.
+
+# Examples
+```jldoctest
+import GeoInterface as GI, GeometryOps as GO
+
+poly = GI.Polygon([[(0, 0), (0, 1), (1, 1), (1, 0), (0, 0)]])
+GO.isconcave(poly)
GI.npoint(exterior) <= 4 && return false
+ n = GI.npoint(exterior) - 1
+
+ for i in 1:n
+ j = ((i + 1) % n) === 0 ? 1 : (i + 1) % n
+ m = ((i + 2) % n) === 0 ? 1 : (i + 2) % n
+
+ pti = GI.getpoint(exterior, i)
+ ptj = GI.getpoint(exterior, j)
+ ptm = GI.getpoint(exterior, m)
+
+ dx1 = GI.x(ptm) - GI.x(ptj)
+ dy1 = GI.y(ptm) - GI.y(ptj)
+ dx2 = GI.x(pti) - GI.x(ptj)
+ dy2 = GI.y(pti) - GI.y(ptj)
+
+ cross = (dx1 * dy2) - (dy1 * dx2)
+
+ if i === 0
+ sign = cross > 0
+ elseif sign !== (cross > 0)
+ return true
+ end
+ end
+
+ return false
+end
This is commented out.
julia
"""
+ isparallel(line1::LineString, line2::LineString)::Bool
+
+Return `true` if each segment of `line1` is parallel to the correspondent segment of `line2`
+
+## Examples
julia import GeoInterface as GI, GeometryOps as GO julia> line1 = GI.LineString([(9.170356, 45.477985), (9.164434, 45.482551), (9.166644, 45.484003)]) GeoInterface.Wrappers.LineString{false, false, Vector{Tuple{Float64, Float64}}, Nothing, Nothing}([(9.170356, 45.477985), (9.164434, 45.482551), (9.166644, 45.484003)], nothing, nothing)
export polygonize
+
+#=
+The methods in this file convert a raster image into a set of polygons,
+by contour detection using a clockwise Moore neighborhood method.
+
+The resulting polygons are snapped to the boundaries of the cells of the input raster,
+so they will look different from traditional contours from a plotting package.
+
+The main entry point is the `polygonize` function.
+
+```@docs
+polygonize
+```
+
+# Example
+
+Here's a basic example, using the `Makie.peaks()` function. First, let's investigate the nature of the function:
+```@example polygonize
+using Makie, GeometryOps
+n = 49
+xs, ys = LinRange(-3, 3, n), LinRange(-3, 3, n)
+zs = Makie.peaks(n)
+z_max_value = maximum(abs.(extrema(zs)))
+f, a, p = heatmap(
+ xs, ys, zs;
+ axis = (; aspect = DataAspect(), title = "Exact function")
+)
+cb = Colorbar(f[1, 2], p; label = "Z-value")
+f
+```
+
+Now, we can use the `polygonize` function to convert the raster data into polygons.
+
+For this particular example, we chose a range of z-values between 0.8 and 3.2,
+which would provide two distinct polyogns with holes.
+
+```@example polygonize
+polygons = polygonize(xs, ys, 0.8 .< zs .< 3.2)
+```
+This returns a `GI.MultiPolygon`, which is directly plottable. Let's see how these look:
+
+```@example polygonize
+f, a, p = poly(polygons; label = "Polygonized polygons", axis = (; aspect = DataAspect()))
+```
+
+Finally, let's plot the Makie contour lines on top, to see how the polygonization compares:
+```@example polygonize
+contour!(a, xs, ys, zs; labels = true, levels = [0.8, 3.2], label = "Contour lines")
+f
+```
+
+# Implementation
+
+The implementation follows:
+=#
+
+"""
+ polygonize(A::AbstractMatrix{Bool}; kw...)
+ polygonize(f, A::AbstractMatrix; kw...)
+ polygonize(xs, ys, A::AbstractMatrix{Bool}; kw...)
+ polygonize(f, xs, ys, A::AbstractMatrix; kw...)
+
+Polygonize an `AbstractMatrix` of values, currently to a single class of polygons.
+
+Returns a `MultiPolygon` for `Bool` values and `f` return values, and
+a `FeatureCollection` of `Feature`s holding `MultiPolygon` for all other values.
+
+
+Function `f` should return either `true` or `false` or a transformation
+of values into simpler groups, especially useful for floating point arrays.
+
+If `xs` and `ys` are ranges, they are used as the pixel/cell center points.
+If they are `Vector` of `Tuple` they are used as the lower and upper bounds of each pixel/cell.
Keywords
julia
- `minpoints`: ignore polygons with less than `minpoints` points.
+- `values`: the values to turn into polygons. By default these are `union(A)`,
+ If function `f` is passed these refer to the return values of `f`, by
+ default `union(map(f, A)`. If values `Bool`, false is ignored and a single
+ `MultiPolygon` is returned rather than a `FeatureCollection`.
When there are two possible node, choose the node that is the furthest to the left We also need to check if we are on a straight line to avoid adding unnecessary points.
julia
selectednode, remainingnode, straightline = if currentnode[1] == nextnode[1] # vertical
+ wasincreasing = nextnode[2] > currentnode[2]
+ firstisstraight = nextnode[1] == c1[1]
+ firstisleft = nextnode[1] > c1[1]
+ secondisstraight = nextnode[1] == c2[1]
+ secondisleft = nextnode[1] > c2[1]
+ if firstisstraight
+ if secondisleft
+ if wasincreasing
+ (c2, c1, turning)
+ else
+ (c1, c2, straight)
+ end
+ else
+ if wasincreasing
+ (c1, c2, straight)
+ else
+ (c2, c1, secondisstraight)
+ end
+ end
+ elseif firstisleft
+ if wasincreasing
+ (c1, c2, turning)
+ else
+ (c2, c1, secondisstraight)
+ end
+ else # firstisright
+ if wasincreasing
+ (c2, c1, secondisstraight)
+ else
+ (c1, c2, turning)
+ end
+ end
+ else # horizontal
+ wasincreasing = nextnode[1] > currentnode[1]
+ firstisstraight = nextnode[2] == c1[2]
+ firstisleft = nextnode[2] > c1[2]
+ secondisleft = nextnode[2] > c2[2]
+ secondisstraight = nextnode[2] == c2[2]
+ if firstisstraight
+ if secondisleft
+ if wasincreasing
+ (c1, c2, straight)
+ else
+ (c2, c1, turning)
+ end
+ else
+ if wasincreasing
+ (c2, c1, turning)
+ else
+ (c1, c2, straight)
+ end
+ end
+ elseif firstisleft
+ if wasincreasing
+ (c2, c1, secondisstraight)
+ else
+ (c1, c2, turning)
+ end
+ else # firstisright
+ if wasincreasing
+ (c1, c2, turning)
+ else
+ (c2, c1, secondisstraight)
+ end
+ end
+ end
Update the current and next nodes with the next and selected nodes
julia
currentnode, nextnode = nextnode, selectednode
Update the current node or add a new node to the ring
julia
if straightline
replace the last node we don't need it
julia
ring[end] = nextnode
+ else
add a new node, we have turned a corner
julia
push!(ring, nextnode)
+ end
If the ring is closed, break the loop and start a new one
julia
nextnode == firstnode && break
+ end
+ end
Define wrapped LinearRings, with embedded extents so we only calculate them once
julia
linearrings = map(rings) do ring
+ extent = GI.extent(GI.LinearRing(ring))
+ GI.LinearRing(ring; extent, crs)
+ end
Separate exteriors from holes by winding direction
julia
direction = (last(last(xs)) - first(first(xs))) * (last(last(ys)) - first(first(ys)))
+ exterior_inds = if direction > 0
+ .!isclockwise.(linearrings)
+ else
+ isclockwise.(linearrings)
+ end
+ holes = linearrings[.!exterior_inds]
+ polygons = map(view(linearrings, exterior_inds)) do lr
+ GI.Polygon([lr]; extent=GI.extent(lr), crs)
+ end
Then we add the holes to the polygons they are inside of
julia
assigned = fill(false, length(holes))
+ for i in eachindex(holes)
+ hole = holes[i]
+ prepared_hole = GI.LinearRing(holes[i]; extent=GI.extent(holes[i]))
+ for poly in polygons
+ exterior = GI.Polygon(StaticArrays.SVector(GI.getexterior(poly)); extent=GI.extent(poly))
+ if covers(exterior, prepared_hole)
Hole is in the exterior, so add it to the polygon
julia
push!(poly.geom, hole)
+ assigned[i] = true
+ break
+ end
+ end
+ end
+
+ assigned_holes = count(assigned)
+ assigned_holes == length(holes) || @warn "Not all holes were assigned to polygons, $(length(holes) - assigned_holes) where missed from $(length(holes)) holes and $(length(polygons)) polygons"
+
+ if isempty(polygons)
TODO: this really should return an emtpty MultiPolygon but GeoInterface wrappers cant do that yet, which is not ideal...
julia
@warn "No polgons found, check your data or try another function for `f`"
+ return nothing
+ else
If we actually fetched an existing node, update it
julia
if existingnodes[1] != node
+ dict[key] = (existingnodes[1], node)
+ end
+end
+
+function _pixel_edges(f, xs::AbstractVector{T}, ys::AbstractVector{T}, A) where T<:Tuple
+ edges = Dict{T,Tuple{T,T}}()
First we collect all the edges around target pixels
julia
fi, fj = map(first, axes(A))
+ li, lj = map(last, axes(A))
+ for j in axes(A, 2)
+ y1, y2 = ys[j]
+ for i in axes(A, 1)
+ if f(A[i, j]) # This is a pixel inside a polygon
xs and ys hold pixel bounds
julia
x1, x2 = xs[i]
We check the Von Neumann neighborhood to decide what edges are needed, if any.
julia
(j == fi || !f(A[i, j-1])) && update_edge!(edges, (x1, y1), (x2, y1)) # S
+ (i == fj || !f(A[i-1, j])) && update_edge!(edges, (x1, y2), (x1, y1)) # W
+ (j == lj || !f(A[i, j+1])) && update_edge!(edges, (x2, y2), (x1, y2)) # N
+ (i == li || !f(A[i+1, j])) && update_edge!(edges, (x2, y1), (x2, y2)) # E
+ end
+ end
+ end
+ return edges
+end
This file mainly defines the apply and applyreduce functions, and some related functionality.
In general, the idea behind the apply framework is to take as input any geometry, vector of geometries, or feature collection, deconstruct it to the given trait target (any arbitrary GI.AbstractTrait or TraitTarget union thereof, like PointTrait or PolygonTrait) and perform some operation on it.
This allows for a simple and consistent framework within which users can define their own operations trivially easily, and removes a lot of the complexity involved with handling complex geometry structures.
For example, a simple way to flip the x and y coordinates of a geometry is:
julia
flipped_geom = GO.apply(GI.PointTrait(), geom) do p
+ (GI.y(p), GI.x(p))
+end
As simple as that. There's no need to implement your own decomposition because it's done for you.
Functions like flip, reproject, transform, even segmentize and simplify have been implemented using the apply framework. Similarly, centroid, area and distance have been implemented using the applyreduce framework.
Lazily flatten any AbstractArray, iterator, FeatureCollectionTrait, FeatureTrait or AbstractGeometryTrait object obj, so that objects with the target trait are returned by the iterator.
If f is passed in it will be applied to the target geometries.
By default geometries will be rebuilt as a GeoInterface.Wrappers geometry, but rebuild can have methods added to it to dispatch on geometries from other packages and specify how to rebuild them.
We pass threading and calc_extent as types, not simple boolean values.
This is to help compilation - with a type to hold on to, it's easier for the compiler to separate threaded and non-threaded code paths.
Note that if we didn't include the parent abstract type, this would have been really type unstable, since the compiler couldn't tell what would be returned!
We had to add the type annotation on the _booltype(::Bool) method for this reason as well.
julia
abstract type BoolsAsTypes end
+struct _True <: BoolsAsTypes end
+struct _False <: BoolsAsTypes end
+
+@inline _booltype(x::Bool)::BoolsAsTypes = x ? _True() : _False()
+@inline _booltype(x::BoolsAsTypes)::BoolsAsTypes = x
+
+"""
+ TraitTarget{T}
+
+This struct holds a trait parameter or a union of trait parameters.
+
+It is primarily used for dispatch into methods which select trait levels,
+like `apply`, or as a parameter to `target`.
+
+# Constructors
+```julia
+TraitTarget(GI.PointTrait())
+TraitTarget(GI.LineStringTrait(), GI.LinearRingTrait()) # and other traits as you may like
+TraitTarget(TraitTarget(...))
There are also type based constructors available, but that's not advised.
```
+
+"""
+struct TraitTarget{T} end
+TraitTarget(::Type{T}) where T = TraitTarget{T}()
+TraitTarget(::T) where T<:GI.AbstractTrait = TraitTarget{T}()
+TraitTarget(::TraitTarget{T}) where T = TraitTarget{T}()
+TraitTarget(::Type{<:TraitTarget{T}}) where T = TraitTarget{T}()
+TraitTarget(traits::GI.AbstractTrait...) = TraitTarget{Union{map(typeof, traits)...}}()
+
+const THREADED_KEYWORD = "- `threaded`: `true` or `false`. Whether to use multithreading. Defaults to `false`."
+const CRS_KEYWORD = "- `crs`: The CRS to attach to geometries. Defaults to `nothing`."
+const CALC_EXTENT_KEYWORD = "- `calc_extent`: `true` or `false`. Whether to calculate the extent. Defaults to `false`."
+
+const APPLY_KEYWORDS = """
+$THREADED_KEYWORD
+$CRS_KEYWORD
+$CALC_EXTENT_KEYWORD
+"""
apply applies some function to every geometry matching the Target GeoInterface trait, in some arbitrarily nested object made up of:
AbstractArrays (we also try to iterate other non-GeoInteface compatible object)
FeatureCollectionTrait objects
FeatureTrait objects
AbstractGeometryTrait objects
apply recursively calls itself through these nested layers until it reaches objects with the Target GeoInterface trait. When found apply applies the function f, and stops.
The outer recursive functions then progressively rebuild the object using GeoInterface objects matching the original traits.
If PointTrait is found but it is not the Target, an error is thrown. This likely means the object contains a different geometry trait to the target, such as MultiPointTrait when LineStringTrait was specified.
To handle this possibility it may be necessary to make Target a Union of traits found at the same level of nesting, and define methods of f to handle all cases.
Be careful making a union across "levels" of nesting, e.g. Union{FeatureTrait,PolygonTrait}, as _apply will just never reach PolygonTrait when all the polygons are wrapped in a FeatureTrait object.
extent and crs can be embedded in all geometries, features, and feature collections as part of apply. Geometries deeper than Target will of course not have new extent or crs embedded.
calc_extent signals to recalculate an Extent and embed it.
Threading is used at the outermost level possible - over an array, feature collection, or e.g. a MultiPolygonTrait where each PolygonTrait sub-geometry may be calculated on a different thread.
Currently, threading defaults to false for all objects, but can be turned on by passing the keyword argument threaded=true to apply.
julia
"""
+ apply(f, target::Union{TraitTarget, GI.AbstractTrait}, obj; kw...)
+
+Reconstruct a geometry, feature, feature collection, or nested vectors of
+either using the function `f` on the `target` trait.
+
+`f(target_geom) => x` where `x` also has the `target` trait, or a trait that can
+be substituted. For example, swapping `PolgonTrait` to `MultiPointTrait` will fail
+if the outer object has `MultiPolygonTrait`, but should work if it has `FeatureTrait`.
+
+Objects "shallower" than the target trait are always completely rebuilt, like
+a `Vector` of `FeatureCollectionTrait` of `FeatureTrait` when the target
+has `PolygonTrait` and is held in the features. These will always be GeoInterface
+geometries/feature/feature collections. But "deeper" objects may remain
+unchanged or be whatever GeoInterface compatible objects `f` returns.
+
+The result is a functionally similar geometry with values depending on `f`.
+
+$APPLY_KEYWORDS
+
+# Example
+
+Flipped point the order in any feature or geometry, or iterables of either:
+
+```julia
+import GeoInterface as GI
+import GeometryOps as GO
+geom = GI.Polygon([GI.LinearRing([(1, 2), (3, 4), (5, 6), (1, 2)]),
+ GI.LinearRing([(3, 4), (5, 6), (6, 7), (3, 4)])])
+
+flipped_geom = GO.apply(GI.PointTrait, geom) do p
+ (GI.y(p), GI.x(p))
+end
+```
+"""
+@inline function apply(
+ f::F, target, geom; calc_extent=false, threaded=false, kw...
+) where F
+ threaded = _booltype(threaded)
+ calc_extent = _booltype(calc_extent)
+ _apply(f, TraitTarget(target), geom; threaded, calc_extent, kw...)
+end
Call _apply again with the trait of geom
julia
@inline _apply(f::F, target, geom; kw...) where F =
+ _apply(f, target, GI.trait(geom), geom; kw...)
There is no trait and this is an AbstractArray - so just iterate over it calling _apply on the contents
julia
@inline function _apply(f::F, target, ::Nothing, A::AbstractArray; threaded, kw...) where F
For an Array there is nothing else to do but map _apply over all values _maptasks may run this level threaded if threaded==true, but deeper _apply called in the closure will not be threaded
There is no trait and this is not an AbstractArray. Try to call _apply over it. We can't use threading as we don't know if we can can index into it. So just map.
julia
@inline function _apply(f::F, target, ::Nothing, iterable::IterableType; threaded, kw...) where {F, IterableType}
Try the Tables.jl interface first
julia
if Tables.istable(iterable)
+ _apply_table(f, target, iterable; threaded, kw...)
+ else # this is probably some form of iterable...
+ if threaded isa _True
collect first so we can use threads
julia
_apply(f, target, collect(iterable); threaded, kw...)
+ else
+ apply_to_iterable(x) = _apply(f, target, x; kw...)
+ map(apply_to_iterable, iterable)
+ end
+ end
+end
+#=
+Doing this inline in `_apply` is _heavily_ type unstable, so it's best to separate this
+by a function barrier.
+
+This function operates `apply` on the `geometry` column of the table, and returns a new table
+with the same schema, but with the new geometry column.
+
+This new table may be of the same type as the old one iff `Tables.materializer` is defined for
+that table. If not, then a `NamedTuple` is returned.
+=#
+function _apply_table(f::F, target, iterable::IterableType; threaded, kw...) where {F, IterableType}
+ _get_col_pair(colname) = colname => Tables.getcolumn(iterable, colname)
We extract the geometry column and run apply on it.
Return a new geometryof the same trait as geom, holding the new geoms with crs
julia
return rebuild(geom, geoms; crs)
+end
Fail loudly if we hit PointTrait without running f (after PointTrait there is no further to dig with _apply) @inline _apply(f, ::TraitTarget{Target}, trait::GI.PointTrait, geom; crs=nothing, kw...) where Target = throw(ArgumentError("target Target not found, but reached a PointTrait leaf")) Finally, these short methods are the main purpose of apply. The Trait is a subtype of the Target (or identical to it) So the Target is found. We apply f to geom and return it to previous _apply calls to be wrapped with the outer geometries/feature/featurecollection/array.
julia
_apply(f::F, ::TraitTarget{Target}, ::Trait, geom; crs=GI.crs(geom), kw...) where {F,Target,Trait<:Target} = f(geom)
Define some specific cases of this match to avoid method ambiguity
julia
for T in (
+ GI.PointTrait, GI.LinearRing, GI.LineString,
+ GI.MultiPoint, GI.FeatureTrait, GI.FeatureCollectionTrait
+)
+ @eval _apply(f::F, target::TraitTarget{<:$T}, trait::$T, x; kw...) where F = f(x)
+end
+
+"""
+ applyreduce(f, op, target::Union{TraitTarget, GI.AbstractTrait}, obj; threaded)
+
+Apply function `f` to all objects with the `target` trait,
+and reduce the result with an `op` like `+`.
+
+The order and grouping of application of `op` is not guaranteed.
+
+If `threaded==true` threads will be used over arrays and iterables,
+feature collections and nested geometries.
+"""
+@inline function applyreduce(
+ f::F, op::O, target, geom; threaded=false, init=nothing
+) where {F, O}
+ threaded = _booltype(threaded)
+ _applyreduce(f, op, TraitTarget(target), geom; threaded, init)
+end
+
+@inline _applyreduce(f::F, op::O, target, geom; threaded, init) where {F, O} =
+ _applyreduce(f, op, target, GI.trait(geom), geom; threaded, init)
@inline function _applyreduce(f::F, op::O, ::TraitTarget{Target}, ::Trait, x; kw...) where {F,O,Target,Trait<:Target}
+ f(x)
+end
Fail if we hit PointTrait _applyreduce(f, op, target::TraitTarget{Target}, trait::PointTrait, geom; kw...) where Target = throw(ArgumentError("target target not found")) Specific cases to avoid method ambiguity
julia
for T in (
+ GI.PointTrait, GI.LinearRing, GI.LineString,
+ GI.MultiPoint, GI.FeatureTrait, GI.FeatureCollectionTrait
+)
+ @eval _applyreduce(f::F, op::O, ::TraitTarget{<:$T}, trait::$T, x; kw...) where {F, O} = f(x)
+end
+
+"""
+ unwrap(target::Type{<:AbstractTrait}, obj)
+ unwrap(f, target::Type{<:AbstractTrait}, obj)
+
+Unwrap the object to vectors, down to the target trait.
+
+If `f` is passed in it will be applied to the target geometries
+as they are found.
+"""
+function unwrap end
+unwrap(target::Type, geom) = unwrap(identity, target, geom)
unwrap(f, ::Type{Target}, ::Trait, geom) where {Target,Trait<:Target} = f(geom)
Fail if we hit PointTrait
julia
unwrap(f, target::Type, trait::GI.PointTrait, geom) =
+ throw(ArgumentError("target $target not found, but reached a `PointTrait` leaf"))
Specific cases to avoid method ambiguity
julia
unwrap(f, target::Type{GI.PointTrait}, trait::GI.PointTrait, geom) = f(geom)
+unwrap(f, target::Type{GI.FeatureTrait}, ::GI.FeatureTrait, feature) = f(feature)
+unwrap(f, target::Type{GI.FeatureCollectionTrait}, ::GI.FeatureCollectionTrait, fc) = f(fc)
+
+"""
+ flatten(target::Type{<:GI.AbstractTrait}, obj)
+ flatten(f, target::Type{<:GI.AbstractTrait}, obj)
+
+Lazily flatten any `AbstractArray`, iterator, `FeatureCollectionTrait`,
+`FeatureTrait` or `AbstractGeometryTrait` object `obj`, so that objects
+with the `target` trait are returned by the iterator.
+
+If `f` is passed in it will be applied to the target geometries.
+"""
+flatten(::Type{Target}, geom) where {Target<:GI.AbstractTrait} = flatten(identity, Target, geom)
+flatten(f, ::Type{Target}, geom) where {Target<:GI.AbstractTrait} = _flatten(f, Target, geom)
+
+_flatten(f, ::Type{Target}, geom) where Target = _flatten(f, Target, GI.trait(geom), geom)
_flatten(f, ::Type{Target}, trait::GI.PointTrait, geom) where Target =
+ throw(ArgumentError("target $Target not found, but reached a `PointTrait` leaf"))
Specific cases to avoid method ambiguity
julia
_flatten(f, ::Type{<:GI.PointTrait}, ::GI.PointTrait, geom) = (f(geom),)
+_flatten(f, ::Type{<:GI.FeatureTrait}, ::GI.FeatureTrait, feature) = (f(feature),)
+_flatten(f, ::Type{<:GI.FeatureCollectionTrait}, ::GI.FeatureCollectionTrait, fc) = (f(fc),)
+
+
+"""
+ reconstruct(geom, components)
+
+Reconstruct `geom` from an iterable of component objects that match its structure.
+
+All objects in `components` must have the same `GeoInterface.trait`.
+
+Ususally used in combination with `flatten`.
+"""
+function reconstruct(geom, components)
+ obj, iter = _reconstruct(geom, components)
+ return obj
+end
+
+_reconstruct(geom, components) =
+ _reconstruct(typeof(GI.trait(first(components))), geom, components, 1)
+_reconstruct(::Type{Target}, geom, components, iter) where Target =
+ _reconstruct(Target, GI.trait(geom), geom, components, iter)
Try to reconstruct over iterables
julia
function _reconstruct(::Type{Target}, ::Nothing, iterable, components, iter) where Target
+ vect = map(iterable) do x
iter is updated by _reconstruct here
julia
obj, iter = _reconstruct(Target, x, components, iter)
+ obj
+ end
+ return vect, iter
+end
Reconstruct feature collections
julia
function _reconstruct(::Type{Target}, ::GI.FeatureCollectionTrait, fc, components, iter) where Target
+ features = map(GI.getfeature(fc)) do feature
iter is updated by _reconstruct here
julia
newfeature, iter = _reconstruct(Target, feature, components, iter)
+ newfeature
+ end
+ return GI.FeatureCollection(features; crs=GI.crs(fc)), iter
+end
+function _reconstruct(::Type{Target}, ::GI.FeatureTrait, feature, components, iter) where Target
+ geom, iter = _reconstruct(Target, GI.geometry(feature), components, iter)
+ return GI.Feature(geom; properties=GI.properties(feature), crs=GI.crs(feature)), iter
+end
+function _reconstruct(::Type{Target}, trait, geom, components, iter) where Target
+ geoms = map(GI.getgeom(geom)) do subgeom
iter is updated by _reconstruct here
julia
subgeom1, iter = _reconstruct(Target, GI.trait(subgeom), subgeom, components, iter)
+ subgeom1
+ end
+ return rebuild(geom, geoms), iter
+end
_reconstruct(::Type{Target}, trait::GI.PointTrait, geom, components, iter) where Target =
+ throw(ArgumentError("target $Target not found, but reached a `PointTrait` leaf"))
+
+
+const BasicsGeoms = Union{GB.AbstractGeometry,GB.AbstractFace,GB.AbstractPoint,GB.AbstractMesh,
+ GB.AbstractPolygon,GB.LineString,GB.MultiPoint,GB.MultiLineString,GB.MultiPolygon,GB.Mesh}
+
+"""
+ rebuild(geom, child_geoms)
+
+Rebuild a geometry from child geometries.
+
+By default geometries will be rebuilt as a `GeoInterface.Wrappers`
+geometry, but `rebuild` can have methods added to it to dispatch
+on geometries from other packages and specify how to rebuild them.
+
+(Maybe it should go into GeoInterface.jl)
+"""
+rebuild(geom, child_geoms; kw...) = rebuild(GI.trait(geom), geom, child_geoms; kw...)
+function rebuild(trait::GI.AbstractTrait, geom, child_geoms; crs=GI.crs(geom), extent=nothing)
+ T = GI.geointerface_geomtype(trait)
+ if GI.is3d(geom)
The Boolean type parameters here indicate "3d-ness" and "measure" coordinate, respectively.
Here we use the compiler directive @assume_effects :foldable to force the compiler to lookup through the closure. This alone makes e.g. flip 2.5x faster!
julia
Base.@assume_effects :foldable @inline function _maptasks(f::F, taskrange, threaded::_False)::Vector where F
+ map(f, taskrange)
+end
Threading utility, modified Mason Protters threading PSA run f over ntasks, where f recieves an AbstractArray/range of linear indices
WARNING: this will not work for mean/median - only ops where grouping is possible
julia
@inline function _mapreducetasks(f::F, op, taskrange, threaded::_True; init) where F
+ ntasks = length(taskrange)
Customize this as needed. More tasks have more overhead, but better load balancing
A closed ring is a ring that has the same start and end point. This is a requirement for a valid polygon (technically, for a valid LinearRing). This correction is used to ensure that the polygon is valid.
The reason this operates on the polygon level is that several packages are loose about whether they return LinearRings (which is correct) or LineStrings (which is incorrect) for the contents of a polygon. Therefore, we decompose manually to ensure correctness.
Many polygon providers do not close their polygons, which makes them invalid according to the specification. Quite a few geometry algorithms assume that polygons are closed, and leaving them open can lead to incorrect results!
For example, the following polygon is not valid:
julia
import GeoInterface as GI
+polygon = GI.Polygon([[(0, 0), (1, 0), (1, 1), (0, 1)]])
"""
+ ClosedRing() <: GeometryCorrection
+
+This correction ensures that a polygon's exterior and interior rings are closed.
+
+It can be called on any geometry correction as usual.
+
+See also `GeometryCorrection`.
+"""
+struct ClosedRing <: GeometryCorrection end
+
+application_level(::ClosedRing) = GI.PolygonTrait
+
+function (::ClosedRing)(::GI.PolygonTrait, polygon)
+ exterior = _close_linear_ring(GI.getexterior(polygon))
+
+ holes = map(GI.gethole(polygon)) do hole
+ _close_linear_ring(hole) # TODO: make this more efficient, or use tuples!
+ end
+
+ return GI.Wrappers.Polygon([exterior, holes...])
+end
+
+function _close_linear_ring(ring)
+ if GI.getpoint(ring, 1) == GI.getpoint(ring, GI.npoint(ring))
All GeometryCorrections are callable structs which, when called, apply the correction to the given geometry, and return either a copy or the original geometry (if nothing needed to be corrected).
This abstract type represents a geometry correction.
Interface
Any GeometryCorrection must implement two functions: * application_level(::GeometryCorrection)::AbstractGeometryTrait: This function should return the GeoInterface trait that the correction is intended to be applied to, like PointTrait or LineStringTrait or PolygonTrait. * (::GeometryCorrection)(::AbstractGeometryTrait, geometry)::(some_geometry): This function should apply the correction to the given geometry, and return a new geometry.
Any geometry correction must implement the interface as given above.
julia
"""
+ abstract type GeometryCorrection
+
+This abstract type represents a geometry correction.
+
+# Interface
+
+Any `GeometryCorrection` must implement two functions:
+ * `application_level(::GeometryCorrection)::AbstractGeometryTrait`: This function should return the `GeoInterface` trait that the correction is intended to be applied to, like `PointTrait` or `LineStringTrait` or `PolygonTrait`.
+ * `(::GeometryCorrection)(::AbstractGeometryTrait, geometry)::(some_geometry)`: This function should apply the correction to the given geometry, and return a new geometry.
+"""
+abstract type GeometryCorrection end
+
+application_level(gc::GeometryCorrection) = error("Not implemented yet for $(gc)")
+
+(gc::GeometryCorrection)(geometry) = gc(GI.trait(geometry), geometry)
+
+(gc::GeometryCorrection)(trait::GI.AbstractGeometryTrait, geometry) = error("Not implemented yet for $(gc) and $(trait).")
+
+function fix(geometry; corrections = GeometryCorrection[ClosedRing(),], kwargs...)
+ traits = application_level.(corrections)
+ final_geometry = geometry
+ for Trait in (GI.PointTrait, GI.MultiPointTrait, GI.LineStringTrait, GI.LinearRingTrait, GI.MultiLineStringTrait, GI.PolygonTrait, GI.MultiPolygonTrait)
+ available_corrections = findall(x -> x == Trait, traits)
+ isempty(available_corrections) && continue
+ @debug "Correcting for $(Trait)"
+ net_function = reduce(∘, corrections[available_corrections])
+ final_geometry = apply(net_function, Trait, final_geometry; kwargs...)
+ end
+ return final_geometry
+end
This correction ensures that the polygons included in a multipolygon aren't intersecting. If any polygon's are intersecting, they will be made nonintersecting through the difference operation to create a unique set of disjoint (other than potentially connections by a single point) polygons covering the same area. See also GeometryCorrection, UnionIntersectingPolygons.
This abstract type represents a geometry correction.
Interface
Any GeometryCorrection must implement two functions: * application_level(::GeometryCorrection)::AbstractGeometryTrait: This function should return the GeoInterface trait that the correction is intended to be applied to, like PointTrait or LineStringTrait or PolygonTrait. * (::GeometryCorrection)(::AbstractGeometryTrait, geometry)::(some_geometry): This function should apply the correction to the given geometry, and return a new geometry.
This correction ensures that the polygon's included in a multipolygon aren't intersecting. If any polygon's are intersecting, they will be combined through the union operation to create a unique set of disjoint (other than potentially connections by a single point) polygons covering the same area.
If the sub-polygons of a multipolygon are intersecting, this makes them invalid according to specification. Each sub-polygon of a multipolygon being disjoint (other than by a single point) is a requirment for a valid multipolygon. However, different libraries may achieve this in different ways.
For example, taking the union of all sub-polygons of a multipolygon will create a new multipolygon where each sub-polygon is disjoint. This can be done with the UnionIntersectingPolygons correction.
The reason this operates on a multipolygon level is that it is easy for users to mistakenly create multipolygon's that overlap, which can then be detrimental to polygon clipping performance and even create wrong answers.
Multipolygon providers may not check that the polygons making up their multipolygons do not intersect, which makes them invalid according to the specification.
For example, the following multipolygon is not valid:
julia
import GeoInterface as GI
+polygon = GI.Polygon([[(0.0, 0.0), (3.0, 0.0), (3.0, 3.0), (0.0, 3.0), (0.0, 0.0)]])
+multipolygon = GI.MultiPolygon([polygon, polygon])
"""
+ UnionIntersectingPolygons() <: GeometryCorrection
+
+This correction ensures that the polygon's included in a multipolygon aren't intersecting.
+If any polygon's are intersecting, they will be combined through the union operation to
+create a unique set of disjoint (other than potentially connections by a single point)
+polygons covering the same area.
+
+See also `GeometryCorrection`.
+"""
+struct UnionIntersectingPolygons <: GeometryCorrection end
+
+application_level(::UnionIntersectingPolygons) = GI.MultiPolygonTrait
+
+function (::UnionIntersectingPolygons)(::GI.MultiPolygonTrait, multipoly)
+ union_multipoly = tuples(multipoly)
+ n_polys = GI.npolygon(multipoly)
+ if n_polys > 1
+ keep_idx = trues(n_polys) # keep track of sub-polygons to remove
Combine any sub-polygons that intersect
julia
for (curr_idx, _) in Iterators.filter(last, Iterators.enumerate(keep_idx))
+ curr_poly = union_multipoly.geom[curr_idx]
+ poly_disjoint = false
+ while !poly_disjoint
+ poly_disjoint = true # assume current polygon is disjoint from others
+ for (next_idx, _) in Iterators.filter(last, Iterators.drop(Iterators.enumerate(keep_idx), curr_idx))
+ next_poly = union_multipoly.geom[next_idx]
+ if intersects(curr_poly, next_poly) # if two polygons intersect
+ new_polys = union(curr_poly, next_poly; target = GI.PolygonTrait())
+ n_new_polys = length(new_polys)
+ if n_new_polys == 1 # if polygons combined
+ poly_disjoint = false
+ union_multipoly.geom[curr_idx] = new_polys[1]
+ curr_poly = union_multipoly.geom[curr_idx]
+ keep_idx[next_idx] = false
+ end
+ end
+ end
+ end
+ end
+ keepat!(union_multipoly.geom, keep_idx)
+ end
+ return union_multipoly
+end
+
+"""
+ DiffIntersectingPolygons() <: GeometryCorrection
+This correction ensures that the polygons included in a multipolygon aren't intersecting.
+If any polygon's are intersecting, they will be made nonintersecting through the `difference`
+operation to create a unique set of disjoint (other than potentially connections by a single point)
+polygons covering the same area.
+See also `GeometryCorrection`, `UnionIntersectingPolygons`.
+"""
+struct DiffIntersectingPolygons <: GeometryCorrection end
+
+application_level(::DiffIntersectingPolygons) = GI.MultiPolygonTrait
+
+function (::DiffIntersectingPolygons)(::GI.MultiPolygonTrait, multipoly)
+ diff_multipoly = tuples(multipoly)
+ n_starting_polys = GI.npolygon(multipoly)
+ n_polys = n_starting_polys
+ if n_polys > 1
+ keep_idx = trues(n_polys) # keep track of sub-polygons to remove
Break apart any sub-polygons that intersect
julia
for curr_idx in 1:n_starting_polys
+ !keep_idx[curr_idx] && continue
+ for next_idx in (curr_idx + 1):n_starting_polys
+ !keep_idx[next_idx] && continue
+ next_poly = diff_multipoly.geom[next_idx]
+ n_new_polys = 0
+ curr_pieces_added = (n_polys + 1):(n_polys + n_new_polys)
+ for curr_piece_idx in Iterators.flatten((curr_idx:curr_idx, curr_pieces_added))
+ !keep_idx[curr_piece_idx] && continue
+ curr_poly = diff_multipoly.geom[curr_piece_idx]
+ if intersects(curr_poly, next_poly) # if two polygons intersect
+ new_polys = difference(curr_poly, next_poly; target = GI.PolygonTrait())
+ n_new_pieces = length(new_polys) - 1
+ if n_new_pieces < 0 # current polygon is covered by next_polygon
+ keep_idx[curr_piece_idx] = false
+ break
+ elseif n_new_pieces ≥ 0
+ diff_multipoly.geom[curr_piece_idx] = new_polys[1]
+ curr_poly = diff_multipoly.geom[curr_piece_idx]
+ if n_new_pieces > 0 # current polygon breaks into several pieces
+ append!(diff_multipoly.geom, @view new_polys[2:end])
+ append!(keep_idx, trues(n_new_pieces))
+ n_new_polys += n_new_pieces
+ end
+ end
+ end
+ end
+ n_polys += n_new_polys
+ end
+ end
+ keepat!(diff_multipoly.geom, keep_idx)
+ end
+ return diff_multipoly
+end
"""
+ embed_extent(obj)
+
+Recursively wrap the object with a GeoInterface.jl geometry,
+calculating and adding an `Extents.Extent` to all objects.
+
+This can improve performance when extents need to be checked multiple times,
+such when needing to check if many points are in geometries, and using their extents
+as a quick filter for obviously exterior points.
This is a simple example of how to use the apply functionality in a function, by flipping the x and y coordinates of a geometry.
julia
"""
+ flip(obj)
+
+Swap all of the x and y coordinates in obj, otherwise
+keeping the original structure (but not necessarily the
+original type).
+
+# Keywords
+
+$APPLY_KEYWORDS
+"""
+function flip(geom; kw...)
+ if _is3d(geom)
+ return apply(PointTrait(), geom; kw...) do p
+ (GI.y(p), GI.x(p), GI.z(p))
+ end
+ else
+ return apply(PointTrait(), geom; kw...) do p
+ (GI.y(p), GI.x(p))
+ end
+ end
+end
This file is pretty simple - it simply reprojects a geometry pointwise from one CRS to another. It uses the Proj package for the transformation, but this could be moved to an extension if needed.
Note that the actual implementation is in the GeometryOpsProjExt extension module.
This works using the apply functionality.
julia
"""
+ reproject(geometry; source_crs, target_crs, transform, always_xy, time)
+ reproject(geometry, source_crs, target_crs; always_xy, time)
+ reproject(geometry, transform; always_xy, time)
+
+Reproject any GeoInterface.jl compatible `geometry` from `source_crs` to `target_crs`.
+
+The returned object will be constructed from `GeoInterface.WrapperGeometry`
+geometries, wrapping views of a `Vector{Proj.Point{D}}`, where `D` is the dimension.
+
+!!! tip
+ The `Proj.jl` package must be loaded for this method to work,
+ since it is implemented in a package extension.
+
+# Arguments
+
+- `geometry`: Any GeoInterface.jl compatible geometries.
+- `source_crs`: the source coordinate referece system, as a GeoFormatTypes.jl object or a string.
+- `target_crs`: the target coordinate referece system, as a GeoFormatTypes.jl object or a string.
+
+If these a passed as keywords, `transform` will take priority.
+Without it `target_crs` is always needed, and `source_crs` is
+needed if it is not retreivable from the geometry with `GeoInterface.crs(geometry)`.
+
+# Keywords
+
+- `always_xy`: force x, y coordinate order, `true` by default.
+ `false` will expect and return points in the crs coordinate order.
+- `time`: the time for the coordinates. `Inf` by default.
+$APPLY_KEYWORDS
+"""
+function reproject end
We also inject a method error handler, which prints a suggestion if the Proj extension is not loaded.
julia
function _reproject_error_hinter(io, exc, argtypes, kwargs)
+ if isnothing(Base.get_extension(GeometryOps, :GeometryOpsProjExt)) && exc.f == reproject
+ print(io, "\n\nThe `reproject` method requires the Proj.jl package to be explicitly loaded.\n")
+ print(io, "You can do this by simply typing ")
+ printstyled(io, "using Proj"; color = :cyan, bold = true)
+ println(io, " in your REPL, \nor otherwise loading Proj.jl via using or import.")
+ else # this is a more general error
+ nothing
+ end
+end
This function "segmentizes" or "densifies" a geometry by adding extra vertices to the geometry so that no segment is longer than a given distance. This is useful for plotting geometries with a limited number of vertices, or for ensuring that a geometry is not too "coarse" for a given application.
Info
We plan to add interpolated segmentization from DataInterpolations.jl in the future, which will be available to any vector of point-like objects.
For now, this function only works on 2D geometries. We will also support 3D geometries, as well as measure interpolation, in the future.
# These are initial distances, which yield similar numbers of points
+# in the final geometry.
+init_lin = 0.01
+init_geo = 900
+
+# LibGEOS.jl doesn't offer this function, so we just wrap it ourselves!
+function densify(obj::LG.Geometry, tol::Real, context::LG.GEOSContext = LG.get_context(obj))
+ result = LG.GEOSDensify_r(context, obj, tol)
+ if result == C_NULL
+ error("LibGEOS: Error in GEOSDensify")
+ end
+ LG.geomFromGEOS(result, context)
+end
+# now, we get to the actual benchmarking:
+for scalefactor in exp10.(LinRange(log10(0.1), log10(10), 5))
+ lin_dist = init_lin * scalefactor
+ geo_dist = init_geo * scalefactor
+
+ npoints_linear = GI.npoint(GO.segmentize(rectangle; max_distance = lin_dist))
+ npoints_geodesic = GO.segmentize(GO.GeodesicSegments(; max_distance = geo_dist), rectangle) |> GI.npoint
+ npoints_libgeos = GI.npoint(densify(lg_rectangle, lin_dist))
+
+ segmentize_suite["Linear"][npoints_linear] = @be GO.segmentize(GO.LinearSegments(; max_distance = $lin_dist), $rectangle) seconds=1
+ segmentize_suite["Geodesic"][npoints_geodesic] = @be GO.segmentize(GO.GeodesicSegments(; max_distance = $geo_dist), $rectangle) seconds=1
+ segmentize_suite["LibGEOS"][npoints_libgeos] = @be densify($lg_rectangle, $lin_dist) seconds=1
+
+end
+
+plot_trials(segmentize_suite)
julia
abstract type SegmentizeMethod end
+"""
+ LinearSegments(; max_distance::Real)
+
+A method for segmentizing geometries by adding extra vertices to the geometry so that no segment is longer than a given distance.
+
+Here, `max_distance` is a purely nondimensional quantity and will apply in the input space. This is to say, that if the polygon is
+provided in lat/lon coordinates then the `max_distance` will be in degrees of arc. If the polygon is provided in meters, then the
+`max_distance` will be in meters.
+"""
+Base.@kwdef struct LinearSegments <: SegmentizeMethod
+ max_distance::Float64
+end
+
+"""
+ GeodesicSegments(; max_distance::Real, equatorial_radius::Real=6378137, flattening::Real=1/298.257223563)
+
+A method for segmentizing geometries by adding extra vertices to the geometry so that no segment is longer than a given distance.
+This method calculates the distance between points on the geodesic, and assumes input in lat/long coordinates.
+
+!!! warning
+ Any input geometries must be in lon/lat coordinates! If not, the method may fail or error.
+
+# Arguments
+- `max_distance::Real`: The maximum distance, **in meters**, between vertices in the geometry.
+- `equatorial_radius::Real=6378137`: The equatorial radius of the Earth, in meters. Passed to `Proj.geod_geodesic`.
+- `flattening::Real=1/298.257223563`: The flattening of the Earth, which is the ratio of the difference between the equatorial and polar radii to the equatorial radius. Passed to `Proj.geod_geodesic`.
+
+One can also omit the `equatorial_radius` and `flattening` keyword arguments, and pass a `geodesic` object directly to the eponymous keyword.
+
+This method uses the Proj/GeographicLib API for geodesic calculations.
+"""
+struct GeodesicSegments{T} <: SegmentizeMethod
+ geodesic::T# ::Proj.geod_geodesic
+ max_distance::Float64
+end
Add an error hint for GeodesicSegments if Proj is not loaded!
julia
function _geodesic_segments_error_hinter(io, exc, argtypes, kwargs)
+ if isnothing(Base.get_extension(GeometryOps, :GeometryOpsProjExt)) && exc.f == GeodesicSegments
+ print(io, "\n\nThe `GeodesicSegments` method requires the Proj.jl package to be explicitly loaded.\n")
+ print(io, "You can do this by simply typing ")
+ printstyled(io, "using Proj"; color = :cyan, bold = true)
+ println(io, " in your REPL, \nor otherwise loading Proj.jl via using or import.")
+ end
+end
"""
+ segmentize([method = LinearSegments()], geom; max_distance::Real, threaded)
+
+Segmentize a geometry by adding extra vertices to the geometry so that no segment is longer than a given distance.
+This is useful for plotting geometries with a limited number of vertices, or for ensuring that a geometry is not too "coarse" for a given application.
+
+# Arguments
+- `method::SegmentizeMethod = LinearSegments()`: The method to use for segmentizing the geometry. At the moment, only `LinearSegments` and `GeodesicSegments` are available.
+- `geom`: The geometry to segmentize. Must be a `LineString`, `LinearRing`, or greater in complexity.
+- `max_distance::Real`: The maximum distance, **in the input space**, between vertices in the geometry. Only used if you don't explicitly pass a `method`.
+
+Returns a geometry of similar type to the input geometry, but resampled.
+"""
+function segmentize(geom; max_distance, threaded::Union{Bool, BoolsAsTypes} = _False())
+ return segmentize(LinearSegments(; max_distance), geom; threaded = _booltype(threaded))
+end
+function segmentize(method::SegmentizeMethod, geom; threaded::Union{Bool, BoolsAsTypes} = _False())
+ @assert method.max_distance > 0 "`max_distance` should be positive and nonzero! Found $(method.max_distance)."
+ segmentize_function = Base.Fix1(_segmentize, method)
+ return apply(segmentize_function, Union{GI.LinearRingTrait, GI.LineStringTrait}, geom; threaded)
+end
+
+_segmentize(method, geom) = _segmentize(method, geom, GI.trait(geom))
+#=
+This is a method which performs the common functionality for both linear and geodesic algorithms,
+and calls out to the "kernel" function which we've defined per linesegment.
+=#
+function _segmentize(method::Union{LinearSegments, GeodesicSegments}, geom, T::Union{GI.LineStringTrait, GI.LinearRingTrait})
+ first_coord = GI.getpoint(geom, 1)
+ x1, y1 = GI.x(first_coord), GI.y(first_coord)
+ new_coords = NTuple{2, Float64}[]
+ sizehint!(new_coords, GI.npoint(geom))
+ push!(new_coords, (x1, y1))
+ for coord in Iterators.drop(GI.getpoint(geom), 1)
+ x2, y2 = GI.x(coord), GI.y(coord)
+ _fill_linear_kernel!(method, new_coords, x1, y1, x2, y2)
+ x1, y1 = x2, y2
+ end
+ return rebuild(geom, new_coords)
+end
+
+function _fill_linear_kernel!(method::LinearSegments, new_coords::Vector, x1, y1, x2, y2)
+ dx, dy = x2 - x1, y2 - y1
+ distance = hypot(dx, dy) # this is a more stable way to compute the Euclidean distance
+ if distance > method.max_distance
+ n_segments = ceil(Int, distance / method.max_distance)
+ for i in 1:(n_segments - 1)
+ t = i / n_segments
+ push!(new_coords, (x1 + t * dx, y1 + t * dy))
+ end
+ end
End the line with the original coordinate, to avoid any multiplication errors.
julia
push!(new_coords, (x2, y2))
+ return nothing
+end
Note
The _fill_linear_kernel definition for GeodesicSegments is in the GeometryOpsProjExt extension module, in the segmentize.jl file.
This file holds implementations for the RadialDistance, Douglas-Peucker, and Visvalingam-Whyatt algorithms for simplifying geometries (specifically for polygons and lines).
multipoly_suite = BenchmarkGroup(["MultiPolygon", "title:Multipolygon simplify", "subtitle:USA multipolygon"])
+
+for frac in exp10.(LinRange(log10(0.3), log10(1), 6)) # TODO: this example isn't the best. How can we get this better?
+ geom = GO.simplify(usa_multipoly; ratio = frac)
+ geom_lg, geom_go = lg_and_go(geom)
+ _tol = 0.001
+ multipoly_suite["GO-DP"][GI.npoint(geom)] = @be GO.simplify($geom_go; tol = $_tol) seconds=1
+ # multipoly_suite["GO-VW"][GI.npoint(geom)] = @be GO.simplify($(GO.VisvalingamWhyatt(; tol = $_tol)), $geom_go) seconds=1
+ multipoly_suite["GO-RD"][GI.npoint(geom)] = @be GO.simplify($(GO.RadialDistance(; tol = _tol)), $geom_go) seconds=1
+ multipoly_suite["LibGEOS"][GI.npoint(geom)] = @be LG.simplify($geom_lg, $_tol) seconds=1
+ println("""
+ For $(GI.npoint(geom)) points, the algorithms generated polygons with the following number of vertices:
+ GO-DP : $(GI.npoint( GO.simplify(geom_go; tol = _tol)))
+ GO-RD : $(GI.npoint( GO.simplify((GO.RadialDistance(; tol = _tol)), geom_go)))
+ LGeos : $(GI.npoint( LG.simplify(geom_lg, _tol)))
+ """)
+ # GO-VW : $(GI.npoint( GO.simplify((GO.VisvalingamWhyatt(; tol = _tol)), geom_go)))
+ println()
+end
+plot_trials(multipoly_suite)
julia
export simplify, VisvalingamWhyatt, DouglasPeucker, RadialDistance
+
+const _SIMPLIFY_TARGET = TraitTarget{Union{GI.PolygonTrait, GI.AbstractCurveTrait, GI.MultiPointTrait, GI.PointTrait}}()
+const MIN_POINTS = 3
+const SIMPLIFY_ALG_KEYWORDS = """
+# Keywords
+
+- `ratio`: the fraction of points that should remain after `simplify`.
+ Useful as it will generalise for large collections of objects.
+- `number`: the number of points that should remain after `simplify`.
+ Less useful for large collections of mixed size objects.
+"""
+const DOUGLAS_PEUCKER_KEYWORDS = """
+$SIMPLIFY_ALG_KEYWORDS
+- `tol`: the minimum distance a point will be from the line
+ joining its neighboring points.
+"""
+
+"""
+ abstract type SimplifyAlg
+
+Abstract type for simplification algorithms.
+
+# API
+
+For now, the algorithm must hold the `number`, `ratio` and `tol` properties.
+
+Simplification algorithm types can hook into the interface by implementing
+the `_simplify(trait, alg, geom)` methods for whichever traits are necessary.
+"""
+abstract type SimplifyAlg end
+
+"""
+ simplify(obj; kw...)
+ simplify(::SimplifyAlg, obj; kw...)
+
+Simplify a geometry, feature, feature collection,
+or nested vectors or a table of these.
+
+`RadialDistance`, `DouglasPeucker`, or
+`VisvalingamWhyatt` algorithms are available,
+listed in order of increasing quality but decreaseing performance.
+
+`PoinTrait` and `MultiPointTrait` are returned unchanged.
+
+The default behaviour is `simplify(DouglasPeucker(; kw...), obj)`.
+Pass in other `SimplifyAlg` to use other algorithms.
Keywords
julia
- `prefilter_alg`: `SimplifyAlg` algorithm used to pre-filter object before
+ using primary filtering algorithm.
+$APPLY_KEYWORDS
+
+
+Keywords for DouglasPeucker are allowed when no algorithm is specified:
+
+$DOUGLAS_PEUCKER_KEYWORDS
"""
+ RadialDistance <: SimplifyAlg
+
+Simplifies geometries by removing points less than
+`tol` distance from the line between its neighboring points.
+
+$SIMPLIFY_ALG_KEYWORDS
+- `tol`: the minimum distance between points.
+
+Note: user input `tol` is squared to avoid uneccesary computation in algorithm.
+"""
+@kwdef struct RadialDistance <: SimplifyAlg
+ number::Union{Int64,Nothing} = nothing
+ ratio::Union{Float64,Nothing} = nothing
+ tol::Union{Float64,Nothing} = nothing
+
+ function RadialDistance(number, ratio, tol)
+ _checkargs(number, ratio, tol)
square tolerance for reduced computation
julia
tol = isnothing(tol) ? tol : tol^2
+ new(number, ratio, tol)
+ end
+end
+
+function _simplify(alg::RadialDistance, points::Vector, _)
+ previous = first(points)
+ distances = Array{Float64}(undef, length(points))
+ for i in eachindex(points)
+ point = points[i]
+ distances[i] = _squared_euclid_distance(Float64, point, previous)
+ previous = point
+ end
+ # Never remove the end points
+ distances[begin] = distances[end] = Inf
+ return _get_points(alg, points, distances)
+end
Loop through points until stopping criteria are fulfilled
julia
i = 2 # already have first and last point added
+ start_idx, end_idx = 1, npoints
+ max_idx, max_dist = _find_max_squared_dist(points, start_idx, end_idx)
+ while i ≤ min(MIN_POINTS + 1, max_points) || (i < max_points && max_dist > max_tol)
Add next point to results
julia
i += 1
+ results[i] = max_idx
Determine which point to add next by checking left and right of point
queue_dist, queue_idx = !isempty(queue) ?
+ findmax(x -> x[4], queue) : (zero(Float64), 0)
+ elseif left_dist > right_dist # use left value as next value to add to results
+ push!(queue, right_vals) # add right value to queue
+ len_queue += 1
+ if right_dist > queue_dist
+ queue_dist = right_dist
+ queue_idx = len_queue
+ end
+ start_idx, max_idx, end_idx, max_dist = left_vals
+ else # use right value as next value to add to results
+ push!(queue, left_vals) # add left value to queue
+ len_queue += 1
+ if left_dist > queue_dist
+ queue_dist = left_dist
+ queue_idx = len_queue
+ end
+ start_idx, max_idx, end_idx, max_dist = right_vals
+ end
+ end
+ sorted_results = sort!(@view results[1:i])
+ if !preserve_endpoint && i > 3
Check start/endpoint distance to other points to see if it meets criteria
if endpt_dist < max_tol
+ results[i] = results[2]
+ sorted_results = @view results[2:i]
+ end
+ else
Remove start point and add point with maximum distance still remaining
julia
if endpt_dist < max_dist
+ insert!(results, searchsortedfirst(sorted_results, max_idx), max_idx)
+ results[i+1] = results[2]
+ sorted_results = @view results[2:i+1]
+ end
+ end
+ end
+ return points[sorted_results]
+end
+
+#= find maximum distance of any point between the start_idx and end_idx to the line formed
+by conencting the points at start_idx and end_idx. Note that the first index of maximum
+value will be used, which might cause differences in results from other algorithms.=#
+function _find_max_squared_dist(points, start_idx, end_idx)
+ max_idx = start_idx
+ max_dist = zero(Float64)
+ for i in (start_idx + 1):(end_idx - 1)
+ d = _squared_distance_line(Float64, points[i], points[start_idx], points[end_idx])
+ if d > max_dist
+ max_dist = d
+ max_idx = i
+ end
+ end
+ return max_idx, max_dist
+end
"""
+ VisvalingamWhyatt <: SimplifyAlg
+
+ VisvalingamWhyatt(; kw...)
+
+Simplifies geometries by removing points below `tol`
+distance from the line between its neighboring points.
+
+$SIMPLIFY_ALG_KEYWORDS
+- `tol`: the minimum area of a triangle made with a point and
+ its neighboring points.
+Note: user input `tol` is doubled to avoid uneccesary computation in algorithm.
+"""
+@kwdef struct VisvalingamWhyatt <: SimplifyAlg
+ number::Union{Int,Nothing} = nothing
+ ratio::Union{Float64,Nothing} = nothing
+ tol::Union{Float64,Nothing} = nothing
+
+ function VisvalingamWhyatt(number, ratio, tol)
+ _checkargs(number, ratio, tol)
double tolerance for reduced computation
julia
tol = isnothing(tol) ? tol : tol*2
+ return new(number, ratio, tol)
+ end
+end
+
+function _simplify(alg::VisvalingamWhyatt, points::Vector, _)
+ length(points) <= MIN_POINTS && return points
+ areas = _build_tolerances(_triangle_double_area, points)
+ return _get_points(alg, points, areas)
+end
Calculates double the area of a triangle given its vertices
function _build_tolerances(f, points)
+ nmax = length(points)
+ real_tolerances = _flat_tolerances(f, points)
+
+ tolerances = copy(real_tolerances)
+ i = [n for n in 1:nmax]
+
+ this_tolerance, min_vert = findmin(tolerances)
+ _remove!(tolerances, min_vert)
+ deleteat!(i, min_vert)
+
+ while this_tolerance < Inf
+ skip = false
+
+ if min_vert < length(i)
+ right_tolerance = f(
+ points[i[min_vert - 1]],
+ points[i[min_vert]],
+ points[i[min_vert + 1]],
+ )
+ if right_tolerance <= this_tolerance
+ right_tolerance = this_tolerance
+ skip = min_vert == 1
+ end
+
+ real_tolerances[i[min_vert]] = right_tolerance
+ tolerances[min_vert] = right_tolerance
+ end
+
+ if min_vert > 2
+ left_tolerance = f(
+ points[i[min_vert - 2]],
+ points[i[min_vert - 1]],
+ points[i[min_vert]],
+ )
+ if left_tolerance <= this_tolerance
+ left_tolerance = this_tolerance
+ skip = min_vert == 2
+ end
+ real_tolerances[i[min_vert - 1]] = left_tolerance
+ tolerances[min_vert - 1] = left_tolerance
+ end
+
+ if !skip
+ min_vert = argmin(tolerances)
+ end
+ deleteat!(i, min_vert)
+ this_tolerance = tolerances[min_vert]
+ _remove!(tolerances, min_vert)
+ end
+
+ return real_tolerances
+end
+
+function tuple_points(geom)
+ points = Array{Tuple{Float64,Float64}}(undef, GI.npoint(geom))
+ for (i, p) in enumerate(GI.getpoint(geom))
+ points[i] = (GI.x(p), GI.y(p))
+ end
+ return points
+end
+
+function _get_points(alg, points, tolerances)
+ # This assumes that `alg` has the properties
+ # `tol`, `number`, and `ratio` available...
+ tol = alg.tol
+ number = alg.number
+ ratio = alg.ratio
+ bit_indices = if !isnothing(tol)
+ _tol_indices(alg.tol::Float64, points, tolerances)
+ elseif !isnothing(number)
+ _number_indices(alg.number::Int64, points, tolerances)
+ else
+ _ratio_indices(alg.ratio::Float64, points, tolerances)
+ end
+ return points[bit_indices]
+end
+
+function _tol_indices(tol, points, tolerances)
+ tolerances .>= tol
+end
+
+function _number_indices(n, points, tolerances)
+ tol = partialsort(tolerances, length(points) - n + 1)
+ bit_indices = _tol_indices(tol, points, tolerances)
+ nselected = sum(bit_indices)
+ # If there are multiple values exactly at `tol` we will get
+ # the wrong output length. So we need to remove some.
+ while nselected > n
+ min_tol = Inf
+ min_i = 0
+ for i in eachindex(bit_indices)
+ bit_indices[i] || continue
+ if tolerances[i] < min_tol
+ min_tol = tolerances[i]
+ min_i = i
+ end
+ end
+ nselected -= 1
+ bit_indices[min_i] = false
+ end
+ return bit_indices
+end
+
+function _ratio_indices(r, points, tolerances)
+ n = max(3, round(Int, r * length(points)))
+ return _number_indices(n, points, tolerances)
+end
+
+function _flat_tolerances(f, points)::Vector{Float64}
+ result = Vector{Float64}(undef, length(points))
+ result[1] = result[end] = Inf
+
+ for i in 2:length(result) - 1
+ result[i] = f(points[i-1], points[i], points[i+1])
+ end
+ return result
+end
+
+function _remove!(s, i)
+ for j in i:lastindex(s)-1
+ s[j] = s[j+1]
+ end
+end
Check SimplifyAlgs inputs to make sure they are valid for below algorithms
julia
function _checkargs(number, ratio, tol)
+ count(isnothing, (number, ratio, tol)) == 2 ||
+ error("Must provide one of `number`, `ratio` or `tol` keywords")
+ if !isnothing(number)
+ if number < MIN_POINTS
+ error("`number` must be $MIN_POINTS or larger. Got $number")
+ end
+ elseif !isnothing(ratio)
+ if ratio <= 0 || ratio > 1
+ error("`ratio` must be 0 < ratio <= 1. Got $ratio")
+ end
+ else # !isnothing(tol)
+ if tol ≤ 0
+ error("`tol` must be a positive number. Got $tol")
+ end
+ end
+ return nothing
+end
"""
+ tuples(obj)
+
+Convert all points in `obj` to `Tuple`s, wherever the are nested.
+
+Returns a similar object or collection of objects using GeoInterface.jl
+geometries wrapping `Tuple` points.
Keywords
julia
$APPLY_KEYWORDS
+"""
+function tuples(geom, ::Type{T} = Float64; kw...) where T
+ if _is3d(geom)
+ return apply(PointTrait(), geom; kw...) do p
+ (T(GI.x(p)), T(GI.y(p)), T(GI.z(p)))
+ end
+ else
+ return apply(PointTrait(), geom; kw...) do p
+ (T(GI.x(p)), T(GI.y(p)))
+ end
+ end
+end
Spatial joins are table joins which are based not on equality, but on some predicate , which takes two geometries, and returns a value of either true or false. For geometries, the DE-9IM spatial relationship model is used to determine the spatial relationship between two geometries.
Spatial joins can be done between any geometry types (from geometrycollections to points), just as geometrical predicates can be evaluated on any geometries.
In this tutorial, we will show how to perform a spatial join on first a toy dataset and then two Natural Earth datasets, to show how this can be used in the real world.
In order to perform the spatial join, we use FlexiJoins.jl to perform the join, specifically using its by_pred joining method. This allows the user to specify a predicate in the following manner:
julia
[inner/left/right/outer/...]join((table1, table1),
+ by_pred(:table1_column, predicate_function, :table2_column) # & add other conditions here
+)
We have enabled the use of all of GeometryOps' boolean comparisons here. These are:
This example demonstrates how to perform a spatial join between two datasets: a set of polygons and a set of randomly generated points.
The polygons are represented as a DataFrame with geometries and colors, while the points are stored in a separate DataFrame.
The spatial join is performed using the contains predicate from GeometryOps, which checks if each point is contained within any of the polygons. The resulting joined DataFrame is then used to plot the points, colored according to the containing polygon.
First, we generate our data. We create two triangle polygons which, together, span the rectangle (0, 0, 1, 1), and a set of points which are randomly distributed within this rectangle.
julia
import GeoInterface as GI, GeometryOps as GO
+using FlexiJoins, DataFrames
+
+using CairoMakie, GeoInterfaceMakie
+
+pl = GI.Polygon([GI.LinearRing([(0, 0), (1, 0), (1, 1), (0, 0)])])
+pu = GI.Polygon([GI.LinearRing([(0, 0), (0, 1), (1, 1), (0, 0)])])
+poly_df = DataFrame(geometry = [pl, pu], color = [:red, :blue])
+f, a, p = poly(poly_df.geometry; color = tuple.(poly_df.color, 0.3))
Here, the upper polygon is blue, and the lower polygon is red. Keep this in mind!
Suppose I have a list of polygons representing administrative regions (or mining sites, or what have you), and I have a list of polygons for each country. I want to find the country each region is in.
julia
import GeoInterface as GI, GeometryOps as GO
+using FlexiJoins, DataFrames, GADM # GADM gives us country and sublevel geometry
+
+using CairoMakie, GeoInterfaceMakie
+
+country_df = GADM.get.(["JPN", "USA", "IND", "DEU", "FRA"]) |> DataFrame
+country_df.geometry = GI.GeometryCollection.(GO.tuples.(country_df.geom))
+
+state_doublets = [
+ ("USA", "New York"),
+ ("USA", "California"),
+ ("IND", "Karnataka"),
+ ("DEU", "Berlin"),
+ ("FRA", "Grand Est"),
+ ("JPN", "Tokyo"),
+]
+
+state_full_df = (x -> GADM.get(x...)).(state_doublets) |> DataFrame
+state_full_df.geom = GO.tuples.(only.(state_full_df.geom))
+state_compact_df = state_full_df[:, [:geom, :NAME_1]]
This is how you would do this, but it doesn't work yet, since the GeometryOps predicates are quite slow on large polygons. If you try this, the code will continue to run for a very, very long time (it took 12 hours on my laptop, but with minimal CPU usage).
![\\"Julia](\\"https://rawcdn.githack.com/JuliaLang/julia-logo-graphics/f3a09eb033b653970c5b8412e7755e3c7d78db9e/images/juliadots.iconset/icon_512x512.png\\"){kind=icon}
","title":"Pure Julia code","details":"Fast, understandable, extensible functions","link":"/introduction"},{"icon":"![](\\"https://fredrikekre.github.io/Literate.jl/v2/assets/logo.png\\"){kind=logo}
","title":"Literate programming","details":"Documented source code with examples!","link":"/source/methods/clipping/cut"},{"icon":"![](\\"https://rawcdn.githack.com/JuliaGeo/juliageo.github.io/4788480c2a5f7ae36df67a4b142e3a963024ac91/img/juliageo.svg\\")
","title":"Full integration with GeoInterface","details":"Use any GeoInterface.jl-compatible geometry","link":"https://juliageo.org/GeoInterface.jl/stable"}]},"headers":[],"relativePath":"index.md","filePath":"index.md","lastUpdated":null}'),s={name:"index.md"},n=e("p",{style:{"margin-bottom":"2cm"}},null,-1),l=e("div",{class:"vp-doc",style:{width:"80%",margin:"auto"}},[e("h1",null," What is GeometryOps.jl? "),e("p",null,"GeometryOps.jl is a package for geometric calculations on (primarily 2D) geometries."),e("p",null,[t("The driving idea behind this package is to unify all the disparate packages for geometric calculations in Julia, and make them "),e("a",{href:"https://github.com/JuliaGeo/GeoInterface.jl",target:"_blank",rel:"noreferrer"},"GeoInterface.jl"),t("-compatible. We seem to be focusing primarily on 2/2.5D geometries for now.")]),e("p",null,"Most of the usecases are driven by GIS and similar Earth data workflows, so this might be a bit specialized towards that, but methods should always be general to any coordinate space."),e("p",null,"We welcome contributions, either as pull requests or discussion on issues!")],-1),r=[n,l];function c(d,u,h,m,g,p){return o(),a("div",null,r)}const _=i(s,[["render",c]]);export{b as __pageData,_ as default};
diff --git a/previews/PR149/assets/index.md.CYCEqvPe.lean.js b/previews/PR149/assets/index.md.CYCEqvPe.lean.js
new file mode 100644
index 000000000..a96067cbc
--- /dev/null
+++ b/previews/PR149/assets/index.md.CYCEqvPe.lean.js
@@ -0,0 +1 @@
+import{_ as i,c as a,o,j as e,a as t}from"./chunks/framework.CDOaXZPW.js";const b=JSON.parse('{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"GeometryOps.jl","text":"","tagline":"Blazing fast geometry operations in pure Julia","image":{"src":"/logo.png","alt":"GeometryOps"},"actions":[{"theme":"brand","text":"Introduction","link":"/introduction"},{"theme":"alt","text":"View on Github","link":"https://github.com/JuliaGeo/GeometryOps.jl"},{"theme":"alt","text":"API Reference","link":"/api"}]},"features":[{"icon":"
