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 reference system, as a GeoFormatTypes.jl object or a string.
target_crs: the target coordinate reference 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 retrievable 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 geometry's 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 definition, 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 definition, 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 slightly 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 polygon 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 struct which instructs the method it's passed to as an algorithm to use the appropriate GEOS function via LibGEOS.jl for the operation.
Dispatch is generally carried out using the names of the keyword arguments. For example, segmentize will only accept a GEOS struct with only a max_distance keyword, and no other.
It's generally a lot slower than the native Julia implementations, since it must convert to the LibGEOS implementation and back - so be warned!
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 (collinear 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 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 polygon 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.
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
Compute the convex hull of the points in geometries. Returns a GI.Polygon representing the convex hull.
Note that the polygon returned is wound counterclockwise as in the Simple Features standard by default. If you choose GEOS, the winding order will be inverted.
Warning
This interface only computes the 2-dimensional convex hull!
For higher dimensional hulls, use the relevant package (Qhull.jl, Quickhull.jl, or similar).
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.
Enforce the presence of a keyword argument in a GEOS algorithm, and return alg.params[kw].
Throws an error if the key is not present, and mentions f in the error message (since there isn't a good way to get the name of the function that called this method).
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 definition, 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 definition, but rings are, so the line must have a repeated last point to be equal
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.
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);
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::Manifold = Planar(): The method to use for segmentizing the geometry. At the moment, only Planar (assumes a flat plane) and Geodesic (assumes geometry on the ellipsoidal Earth and uses Vincenty's formulae) are available.
geom: The geometry to segmentize. Must be a LineString, LinearRing, Polygon, MultiPolygon, or GeometryCollection, or some vector or table of those.
max_distance::Real: The maximum distance between vertices in the geometry. Beware: for Planar, this is in the units of the geometry, but for Geodesic and Spherical it's in units of the radius of the sphere.
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 slightly 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 geometry's 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
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 reference system, as a GeoFormatTypes.jl object or a string.
target_crs: the target coordinate reference 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 retrievable 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 geometry's 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
`,6))]),s[321]||(s[321]=i("h3",{id:"Other-general-methods",tabindex:"-1"},[e("Other general methods "),i("a",{class:"header-anchor",href:"#Other-general-methods","aria-label":'Permalink to "Other general methods {#Other-general-methods}"'},"")],-1)),i("details",G,[i("summary",null,[s[39]||(s[39]=i("a",{id:"GeometryOps.equals",href:"#GeometryOps.equals"},[i("span",{class:"jlbinding"},"GeometryOps.equals")],-1)),s[40]||(s[40]=e()),n(t,{type:"info",class:"jlObjectType jlFunction",text:"Function"})]),s[41]||(s[41]=a(`
julia
equals(geom1, geom2)::Bool
Compare two Geometries return true if they are the same geometry.
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([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+
+GO.equals(poly1, poly2)
+# 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 definition, 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 definition, 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 slightly 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 polygon 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).
',5))]),s[323]||(s[323]=i("h2",{id:"Other-methods",tabindex:"-1"},[e("Other methods "),i("a",{class:"header-anchor",href:"#Other-methods","aria-label":'Permalink to "Other methods {#Other-methods}"'},"")],-1)),i("details",I,[i("summary",null,[s[72]||(s[72]=i("a",{id:"GeometryOps.AbstractBarycentricCoordinateMethod",href:"#GeometryOps.AbstractBarycentricCoordinateMethod"},[i("span",{class:"jlbinding"},"GeometryOps.AbstractBarycentricCoordinateMethod")],-1)),s[73]||(s[73]=e()),n(t,{type:"info",class:"jlObjectType jlType",text:"Type"})]),s[74]||(s[74]=a('
julia
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:
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 struct which instructs the method it's passed to as an algorithm to use the appropriate GEOS function via LibGEOS.jl for the operation.
Dispatch is generally carried out using the names of the keyword arguments. For example, segmentize will only accept a GEOS struct with only a max_distance keyword, and no other.
It's generally a lot slower than the native Julia implementations, since it must convert to the LibGEOS implementation and back - so be warned!
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 (collinear 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 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)
',3))]),i("details",Y,[i("summary",null,[s[126]||(s[126]=i("a",{id:"GeometryOps.angles-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat",href:"#GeometryOps.angles-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat"},[i("span",{class:"jlbinding"},"GeometryOps.angles")],-1)),s[127]||(s[127]=e()),n(t,{type:"info",class:"jlObjectType jlMethod",text:"Method"})]),s[128]||(s[128]=a(`
julia
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 polygon 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.
`,5))]),i("details",ss,[i("summary",null,[s[129]||(s[129]=i("a",{id:"GeometryOps.area-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat",href:"#GeometryOps.area-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat"},[i("span",{class:"jlbinding"},"GeometryOps.area")],-1)),s[130]||(s[130]=e()),n(t,{type:"info",class:"jlObjectType jlMethod",text:"Method"})]),s[131]||(s[131]=a(`
julia
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.
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
Compute the convex hull of the points in geometries. Returns a GI.Polygon representing the convex hull.
Note that the polygon returned is wound counterclockwise as in the Simple Features standard by default. If you choose GEOS, the winding order will be inverted.
Warning
This interface only computes the 2-dimensional convex hull!
For higher dimensional hulls, use the relevant package (Qhull.jl, Quickhull.jl, or similar).
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
`,6))]),i("details",gs,[i("summary",null,[s[168]||(s[168]=i("a",{id:"GeometryOps.cut-Union{Tuple{T}, Tuple{Any, Any}, Tuple{Any, Any, Type{T}}} where T<:AbstractFloat",href:"#GeometryOps.cut-Union{Tuple{T}, Tuple{Any, Any}, Tuple{Any, Any, Type{T}}} where T<:AbstractFloat"},[i("span",{class:"jlbinding"},"GeometryOps.cut")],-1)),s[169]||(s[169]=e()),n(t,{type:"info",class:"jlObjectType jlMethod",text:"Method"})]),s[170]||(s[170]=a(`
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.
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.
`,6))]),i("details",cs,[i("summary",null,[s[177]||(s[177]=i("a",{id:"GeometryOps.distance-Union{Tuple{T}, Tuple{Any, Any}, Tuple{Any, Any, Type{T}}} where T<:AbstractFloat",href:"#GeometryOps.distance-Union{Tuple{T}, Tuple{Any, Any}, Tuple{Any, Any, Type{T}}} where T<:AbstractFloat"},[i("span",{class:"jlbinding"},"GeometryOps.distance")],-1)),s[178]||(s[178]=e()),n(t,{type:"info",class:"jlObjectType jlMethod",text:"Method"})]),s[179]||(s[179]=a('
julia
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.
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.
Enforce the presence of a keyword argument in a GEOS algorithm, and return alg.params[kw].
Throws an error if the key is not present, and mentions f in the error message (since there isn't a good way to get the name of the function that called this method).
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 definition, 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 definition, but rings are, so the line must have a repeated last point to be equal
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.
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);
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::Manifold = Planar(): The method to use for segmentizing the geometry. At the moment, only Planar (assumes a flat plane) and Geodesic (assumes geometry on the ellipsoidal Earth and uses Vincenty's formulae) are available.
geom: The geometry to segmentize. Must be a LineString, LinearRing, Polygon, MultiPolygon, or GeometryCollection, or some vector or table of those.
max_distance::Real: The maximum distance between vertices in the geometry. Beware: for Planar, this is in the units of the geometry, but for Geodesic and Spherical it's in units of the radius of the sphere.
Returns a geometry of similar type to the input geometry, but resampled.
',6))]),i("details",Ys,[i("summary",null,[s[285]||(s[285]=i("a",{id:"GeometryOps.signed_area-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat",href:"#GeometryOps.signed_area-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat"},[i("span",{class:"jlbinding"},"GeometryOps.signed_area")],-1)),s[286]||(s[286]=e()),n(t,{type:"info",class:"jlObjectType jlMethod",text:"Method"})]),s[287]||(s[287]=a(`
julia
signed_area(geom, [T = Float64])::T
Returns the signed area of a single geometry, based on winding order. This is computed slightly 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 geometry's 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
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 reference system, as a GeoFormatTypes.jl object or a string.
target_crs: the target coordinate reference 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 retrievable 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 geometry's 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
`,6))]),s[321]||(s[321]=i("h3",{id:"Other-general-methods",tabindex:"-1"},[e("Other general methods "),i("a",{class:"header-anchor",href:"#Other-general-methods","aria-label":'Permalink to "Other general methods {#Other-general-methods}"'},"")],-1)),i("details",G,[i("summary",null,[s[39]||(s[39]=i("a",{id:"GeometryOps.equals",href:"#GeometryOps.equals"},[i("span",{class:"jlbinding"},"GeometryOps.equals")],-1)),s[40]||(s[40]=e()),n(t,{type:"info",class:"jlObjectType jlFunction",text:"Function"})]),s[41]||(s[41]=a(`
julia
equals(geom1, geom2)::Bool
Compare two Geometries return true if they are the same geometry.
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([[(0,0), (0,5), (5,5), (5,0), (0,0)]])
+
+GO.equals(poly1, poly2)
+# 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 definition, 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 definition, 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 slightly 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 polygon 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).
',5))]),s[323]||(s[323]=i("h2",{id:"Other-methods",tabindex:"-1"},[e("Other methods "),i("a",{class:"header-anchor",href:"#Other-methods","aria-label":'Permalink to "Other methods {#Other-methods}"'},"")],-1)),i("details",I,[i("summary",null,[s[72]||(s[72]=i("a",{id:"GeometryOps.AbstractBarycentricCoordinateMethod",href:"#GeometryOps.AbstractBarycentricCoordinateMethod"},[i("span",{class:"jlbinding"},"GeometryOps.AbstractBarycentricCoordinateMethod")],-1)),s[73]||(s[73]=e()),n(t,{type:"info",class:"jlObjectType jlType",text:"Type"})]),s[74]||(s[74]=a('
julia
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:
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 struct which instructs the method it's passed to as an algorithm to use the appropriate GEOS function via LibGEOS.jl for the operation.
Dispatch is generally carried out using the names of the keyword arguments. For example, segmentize will only accept a GEOS struct with only a max_distance keyword, and no other.
It's generally a lot slower than the native Julia implementations, since it must convert to the LibGEOS implementation and back - so be warned!
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 (collinear 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 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)
',3))]),i("details",Y,[i("summary",null,[s[126]||(s[126]=i("a",{id:"GeometryOps.angles-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat",href:"#GeometryOps.angles-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat"},[i("span",{class:"jlbinding"},"GeometryOps.angles")],-1)),s[127]||(s[127]=e()),n(t,{type:"info",class:"jlObjectType jlMethod",text:"Method"})]),s[128]||(s[128]=a(`
julia
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 polygon 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.
`,5))]),i("details",ss,[i("summary",null,[s[129]||(s[129]=i("a",{id:"GeometryOps.area-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat",href:"#GeometryOps.area-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat"},[i("span",{class:"jlbinding"},"GeometryOps.area")],-1)),s[130]||(s[130]=e()),n(t,{type:"info",class:"jlObjectType jlMethod",text:"Method"})]),s[131]||(s[131]=a(`
julia
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.
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
Compute the convex hull of the points in geometries. Returns a GI.Polygon representing the convex hull.
Note that the polygon returned is wound counterclockwise as in the Simple Features standard by default. If you choose GEOS, the winding order will be inverted.
Warning
This interface only computes the 2-dimensional convex hull!
For higher dimensional hulls, use the relevant package (Qhull.jl, Quickhull.jl, or similar).
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
`,6))]),i("details",gs,[i("summary",null,[s[168]||(s[168]=i("a",{id:"GeometryOps.cut-Union{Tuple{T}, Tuple{Any, Any}, Tuple{Any, Any, Type{T}}} where T<:AbstractFloat",href:"#GeometryOps.cut-Union{Tuple{T}, Tuple{Any, Any}, Tuple{Any, Any, Type{T}}} where T<:AbstractFloat"},[i("span",{class:"jlbinding"},"GeometryOps.cut")],-1)),s[169]||(s[169]=e()),n(t,{type:"info",class:"jlObjectType jlMethod",text:"Method"})]),s[170]||(s[170]=a(`
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.
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.
`,6))]),i("details",cs,[i("summary",null,[s[177]||(s[177]=i("a",{id:"GeometryOps.distance-Union{Tuple{T}, Tuple{Any, Any}, Tuple{Any, Any, Type{T}}} where T<:AbstractFloat",href:"#GeometryOps.distance-Union{Tuple{T}, Tuple{Any, Any}, Tuple{Any, Any, Type{T}}} where T<:AbstractFloat"},[i("span",{class:"jlbinding"},"GeometryOps.distance")],-1)),s[178]||(s[178]=e()),n(t,{type:"info",class:"jlObjectType jlMethod",text:"Method"})]),s[179]||(s[179]=a('
julia
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.
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.
Enforce the presence of a keyword argument in a GEOS algorithm, and return alg.params[kw].
Throws an error if the key is not present, and mentions f in the error message (since there isn't a good way to get the name of the function that called this method).
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 definition, 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 definition, but rings are, so the line must have a repeated last point to be equal
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.
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);
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::Manifold = Planar(): The method to use for segmentizing the geometry. At the moment, only Planar (assumes a flat plane) and Geodesic (assumes geometry on the ellipsoidal Earth and uses Vincenty's formulae) are available.
geom: The geometry to segmentize. Must be a LineString, LinearRing, Polygon, MultiPolygon, or GeometryCollection, or some vector or table of those.
max_distance::Real: The maximum distance between vertices in the geometry. Beware: for Planar, this is in the units of the geometry, but for Geodesic and Spherical it's in units of the radius of the sphere.
Returns a geometry of similar type to the input geometry, but resampled.
',6))]),i("details",Ys,[i("summary",null,[s[285]||(s[285]=i("a",{id:"GeometryOps.signed_area-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat",href:"#GeometryOps.signed_area-Union{Tuple{Any}, Tuple{T}, Tuple{Any, Type{T}}} where T<:AbstractFloat"},[i("span",{class:"jlbinding"},"GeometryOps.signed_area")],-1)),s[286]||(s[286]=e()),n(t,{type:"info",class:"jlObjectType jlMethod",text:"Method"})]),s[287]||(s[287]=a(`
julia
signed_area(geom, [T = Float64])::T
Returns the signed area of a single geometry, based on winding order. This is computed slightly 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 geometry's 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. ↩︎
',2))])}const Fi=h(r,[["render",oi]]);export{mi as __pageData,Fi as default};
diff --git a/previews/PR239/assets/app.CZ1qv-bZ.js b/previews/PR239/assets/app.CZ1qv-bZ.js
new file mode 100644
index 000000000..e1c58d33e
--- /dev/null
+++ b/previews/PR239/assets/app.CZ1qv-bZ.js
@@ -0,0 +1 @@
+import{R as p}from"./chunks/theme.CkNAWswv.js";import{R as o,a6 as u,a7 as c,a8 as l,a9 as f,aa as d,ab as m,ac as h,ad as g,ae as A,af as v,d as P,u as R,v as w,s as y,ag as C,ah as b,ai as E,a4 as S}from"./chunks/framework.onQNwZ2I.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(p),T=P({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=R();return w(()=>{y(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&C(),b(),E(),s.setup&&s.setup(),()=>S(s.Layout)}});async function D(){globalThis.__VITEPRESS__=!0;const e=j(),a=_();a.provide(c,e);const t=l(e.route);return a.provide(f,t),a.component("Content",d),a.component("ClientOnly",m),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:h}),{app:a,router:e,data:t}}function _(){return g(T)}function j(){let e=o,a;return A(t=>{let n=v(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&&D().then(({app:e,router:a,data:t})=>{a.go().then(()=>{u(a.route,t.site),e.mount("#app")})});export{D as createApp};
diff --git a/previews/PR239/assets/bnkpkoa.rOsRk89v.png b/previews/PR239/assets/bnkpkoa.rOsRk89v.png
new file mode 100644
index 000000000..9f49cef5a
Binary files /dev/null and b/previews/PR239/assets/bnkpkoa.rOsRk89v.png differ
diff --git a/previews/PR239/assets/call_notes.md.D1Aj_9mC.js b/previews/PR239/assets/call_notes.md.D1Aj_9mC.js
new file mode 100644
index 000000000..23a9a2a60
--- /dev/null
+++ b/previews/PR239/assets/call_notes.md.D1Aj_9mC.js
@@ -0,0 +1 @@
+import{_ as i,c as l,a5 as t,o}from"./chunks/framework.onQNwZ2I.js";const u=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"call_notes.md","filePath":"call_notes.md","lastUpdated":null}'),a={name:"call_notes.md"};function r(n,e,s,p,c,d){return o(),l("div",null,e[0]||(e[0]=[t('
Rename bools.jl to something more relevant to the actual code -> orientation.jl
Doc improvements:
organise sections
',8)]))}const f=i(a,[["render",r]]);export{u as __pageData,f as default};
diff --git a/previews/PR239/assets/call_notes.md.D1Aj_9mC.lean.js b/previews/PR239/assets/call_notes.md.D1Aj_9mC.lean.js
new file mode 100644
index 000000000..23a9a2a60
--- /dev/null
+++ b/previews/PR239/assets/call_notes.md.D1Aj_9mC.lean.js
@@ -0,0 +1 @@
+import{_ as i,c as l,a5 as t,o}from"./chunks/framework.onQNwZ2I.js";const u=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"call_notes.md","filePath":"call_notes.md","lastUpdated":null}'),a={name:"call_notes.md"};function r(n,e,s,p,c,d){return o(),l("div",null,e[0]||(e[0]=[t('
@example accurate GI.Polygon.(GO.flatten(Union{GI.LineStringTrait, GI.LinearRingTrait}, all_adm0) |> collect .|> x -> [x]) .|> GO.signed_area |> sum_kbn \`\`\`
`,16)]))}const E=i(n,[["render",l]]);export{g as __pageData,E as default};
diff --git a/previews/PR239/assets/experiments_accurate_accumulators.md.C1U7KOjF.lean.js b/previews/PR239/assets/experiments_accurate_accumulators.md.C1U7KOjF.lean.js
new file mode 100644
index 000000000..eb05109cf
--- /dev/null
+++ b/previews/PR239/assets/experiments_accurate_accumulators.md.C1U7KOjF.lean.js
@@ -0,0 +1,6 @@
+import{_ as i,c as a,a5 as t,o as e}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Accurate accumulation","description":"","frontmatter":{},"headers":[],"relativePath":"experiments/accurate_accumulators.md","filePath":"experiments/accurate_accumulators.md","lastUpdated":null}'),n={name:"experiments/accurate_accumulators.md"};function l(h,s,p,k,d,r){return e(),a("div",null,s[0]||(s[0]=[t(`
@example accurate GI.Polygon.(GO.flatten(Union{GI.LineStringTrait, GI.LinearRingTrait}, all_adm0) |> collect .|> x -> [x]) .|> GO.signed_area |> sum_kbn \`\`\`
`,16)]))}const E=i(n,[["render",l]]);export{g as __pageData,E as default};
diff --git a/previews/PR239/assets/experiments_predicates.md.C2d7Qctz.js b/previews/PR239/assets/experiments_predicates.md.C2d7Qctz.js
new file mode 100644
index 000000000..eec97f2c7
--- /dev/null
+++ b/previews/PR239/assets/experiments_predicates.md.C2d7Qctz.js
@@ -0,0 +1,98 @@
+import{_ as i,c as a,a5 as h,o as k}from"./chunks/framework.onQNwZ2I.js";const n="/GeometryOps.jl/previews/PR239/assets/ievlkku.5DNJaCuT.png",y=JSON.parse('{"title":"Predicates","description":"","frontmatter":{},"headers":[],"relativePath":"experiments/predicates.md","filePath":"experiments/predicates.md","lastUpdated":null}'),p={name:"experiments/predicates.md"};function l(t,s,E,e,r,d){return k(),a("div",null,s[0]||(s[0]=[h(`
`,10)]))}const F=i(p,[["render",l]]);export{y as __pageData,F as default};
diff --git a/previews/PR239/assets/experiments_predicates.md.C2d7Qctz.lean.js b/previews/PR239/assets/experiments_predicates.md.C2d7Qctz.lean.js
new file mode 100644
index 000000000..eec97f2c7
--- /dev/null
+++ b/previews/PR239/assets/experiments_predicates.md.C2d7Qctz.lean.js
@@ -0,0 +1,98 @@
+import{_ as i,c as a,a5 as h,o as k}from"./chunks/framework.onQNwZ2I.js";const n="/GeometryOps.jl/previews/PR239/assets/ievlkku.5DNJaCuT.png",y=JSON.parse('{"title":"Predicates","description":"","frontmatter":{},"headers":[],"relativePath":"experiments/predicates.md","filePath":"experiments/predicates.md","lastUpdated":null}'),p={name:"experiments/predicates.md"};function l(t,s,E,e,r,d){return k(),a("div",null,s[0]||(s[0]=[h(`
`,10)]))}const F=i(p,[["render",l]]);export{y as __pageData,F as default};
diff --git a/previews/PR239/assets/explanations_crs.md.BdkIxIey.js b/previews/PR239/assets/explanations_crs.md.BdkIxIey.js
new file mode 100644
index 000000000..f01c24a96
--- /dev/null
+++ b/previews/PR239/assets/explanations_crs.md.BdkIxIey.js
@@ -0,0 +1 @@
+import{_ as e,c as t,o as a}from"./chunks/framework.onQNwZ2I.js";const _=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"explanations/crs.md","filePath":"explanations/crs.md","lastUpdated":null}'),s={name:"explanations/crs.md"};function n(r,o,c,p,i,l){return a(),t("div")}const m=e(s,[["render",n]]);export{_ as __pageData,m as default};
diff --git a/previews/PR239/assets/explanations_crs.md.BdkIxIey.lean.js b/previews/PR239/assets/explanations_crs.md.BdkIxIey.lean.js
new file mode 100644
index 000000000..f01c24a96
--- /dev/null
+++ b/previews/PR239/assets/explanations_crs.md.BdkIxIey.lean.js
@@ -0,0 +1 @@
+import{_ as e,c as t,o as a}from"./chunks/framework.onQNwZ2I.js";const _=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"explanations/crs.md","filePath":"explanations/crs.md","lastUpdated":null}'),s={name:"explanations/crs.md"};function n(r,o,c,p,i,l){return a(),t("div")}const m=e(s,[["render",n]]);export{_ as __pageData,m as default};
diff --git a/previews/PR239/assets/explanations_paradigms.md.B5COLxNa.js b/previews/PR239/assets/explanations_paradigms.md.B5COLxNa.js
new file mode 100644
index 000000000..ebf2c4ccd
--- /dev/null
+++ b/previews/PR239/assets/explanations_paradigms.md.B5COLxNa.js
@@ -0,0 +1 @@
+import{_ as a,c as t,a5 as o,o as i}from"./chunks/framework.onQNwZ2I.js";const u=JSON.parse('{"title":"Paradigms","description":"","frontmatter":{},"headers":[],"relativePath":"explanations/paradigms.md","filePath":"explanations/paradigms.md","lastUpdated":null}'),r={name:"explanations/paradigms.md"};function s(n,e,d,p,c,l){return i(),t("div",null,e[0]||(e[0]=[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)]))}const m=a(r,[["render",s]]);export{u as __pageData,m as default};
diff --git a/previews/PR239/assets/explanations_paradigms.md.B5COLxNa.lean.js b/previews/PR239/assets/explanations_paradigms.md.B5COLxNa.lean.js
new file mode 100644
index 000000000..ebf2c4ccd
--- /dev/null
+++ b/previews/PR239/assets/explanations_paradigms.md.B5COLxNa.lean.js
@@ -0,0 +1 @@
+import{_ as a,c as t,a5 as o,o as i}from"./chunks/framework.onQNwZ2I.js";const u=JSON.parse('{"title":"Paradigms","description":"","frontmatter":{},"headers":[],"relativePath":"explanations/paradigms.md","filePath":"explanations/paradigms.md","lastUpdated":null}'),r={name:"explanations/paradigms.md"};function s(n,e,d,p,c,l){return i(),t("div",null,e[0]||(e[0]=[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)]))}const m=a(r,[["render",s]]);export{u as __pageData,m as default};
diff --git a/previews/PR239/assets/explanations_peculiarities.md.Cphx4jNo.js b/previews/PR239/assets/explanations_peculiarities.md.Cphx4jNo.js
new file mode 100644
index 000000000..8dd61995b
--- /dev/null
+++ b/previews/PR239/assets/explanations_peculiarities.md.Cphx4jNo.js
@@ -0,0 +1 @@
+import{_ as o,c as t,a5 as a,o as r}from"./chunks/framework.onQNwZ2I.js";const u=JSON.parse('{"title":"Peculiarities","description":"","frontmatter":{},"headers":[],"relativePath":"explanations/peculiarities.md","filePath":"explanations/peculiarities.md","lastUpdated":null}'),n={name:"explanations/peculiarities.md"};function i(s,e,l,d,c,p){return r(),t("div",null,e[0]||(e[0]=[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)]))}const y=o(n,[["render",i]]);export{u as __pageData,y as default};
diff --git a/previews/PR239/assets/explanations_peculiarities.md.Cphx4jNo.lean.js b/previews/PR239/assets/explanations_peculiarities.md.Cphx4jNo.lean.js
new file mode 100644
index 000000000..8dd61995b
--- /dev/null
+++ b/previews/PR239/assets/explanations_peculiarities.md.Cphx4jNo.lean.js
@@ -0,0 +1 @@
+import{_ as o,c as t,a5 as a,o as r}from"./chunks/framework.onQNwZ2I.js";const u=JSON.parse('{"title":"Peculiarities","description":"","frontmatter":{},"headers":[],"relativePath":"explanations/peculiarities.md","filePath":"explanations/peculiarities.md","lastUpdated":null}'),n={name:"explanations/peculiarities.md"};function i(s,e,l,d,c,p){return r(),t("div",null,e[0]||(e[0]=[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)]))}const y=o(n,[["render",i]]);export{u as __pageData,y as default};
diff --git a/previews/PR239/assets/explanations_winding_order.md.0V2FnJmC.js b/previews/PR239/assets/explanations_winding_order.md.0V2FnJmC.js
new file mode 100644
index 000000000..bbc6c7dd5
--- /dev/null
+++ b/previews/PR239/assets/explanations_winding_order.md.0V2FnJmC.js
@@ -0,0 +1 @@
+import{_ as e,c as n,o as t}from"./chunks/framework.onQNwZ2I.js";const l=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"explanations/winding_order.md","filePath":"explanations/winding_order.md","lastUpdated":null}'),a={name:"explanations/winding_order.md"};function r(o,i,d,s,c,p){return t(),n("div")}const m=e(a,[["render",r]]);export{l as __pageData,m as default};
diff --git a/previews/PR239/assets/explanations_winding_order.md.0V2FnJmC.lean.js b/previews/PR239/assets/explanations_winding_order.md.0V2FnJmC.lean.js
new file mode 100644
index 000000000..bbc6c7dd5
--- /dev/null
+++ b/previews/PR239/assets/explanations_winding_order.md.0V2FnJmC.lean.js
@@ -0,0 +1 @@
+import{_ as e,c as n,o as t}from"./chunks/framework.onQNwZ2I.js";const l=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"explanations/winding_order.md","filePath":"explanations/winding_order.md","lastUpdated":null}'),a={name:"explanations/winding_order.md"};function r(o,i,d,s,c,p){return t(),n("div")}const m=e(a,[["render",r]]);export{l as __pageData,m as default};
diff --git a/previews/PR239/assets/eytjybr.BEFUMtlf.png b/previews/PR239/assets/eytjybr.BEFUMtlf.png
new file mode 100644
index 000000000..b400f44a5
Binary files /dev/null and b/previews/PR239/assets/eytjybr.BEFUMtlf.png differ
diff --git a/previews/PR239/assets/filtvpm.mCtKcWOr.png b/previews/PR239/assets/filtvpm.mCtKcWOr.png
new file mode 100644
index 000000000..c76dcbee9
Binary files /dev/null and b/previews/PR239/assets/filtvpm.mCtKcWOr.png differ
diff --git a/previews/PR239/assets/fyfzmss.Dab1-ETk.png b/previews/PR239/assets/fyfzmss.Dab1-ETk.png
new file mode 100644
index 000000000..7c32623e0
Binary files /dev/null and b/previews/PR239/assets/fyfzmss.Dab1-ETk.png differ
diff --git a/previews/PR239/assets/hvyhqaw.CgiryX2p.png b/previews/PR239/assets/hvyhqaw.CgiryX2p.png
new file mode 100644
index 000000000..dcf01fb21
Binary files /dev/null and b/previews/PR239/assets/hvyhqaw.CgiryX2p.png differ
diff --git a/previews/PR239/assets/ibdeule.BD0hVfse.png b/previews/PR239/assets/ibdeule.BD0hVfse.png
new file mode 100644
index 000000000..212d1e6a0
Binary files /dev/null and b/previews/PR239/assets/ibdeule.BD0hVfse.png differ
diff --git a/previews/PR239/assets/ievlkku.5DNJaCuT.png b/previews/PR239/assets/ievlkku.5DNJaCuT.png
new file mode 100644
index 000000000..450196afd
Binary files /dev/null and b/previews/PR239/assets/ievlkku.5DNJaCuT.png differ
diff --git a/previews/PR239/assets/index.md.C-gmTcRS.js b/previews/PR239/assets/index.md.C-gmTcRS.js
new file mode 100644
index 000000000..0fe9ce310
--- /dev/null
+++ b/previews/PR239/assets/index.md.C-gmTcRS.js
@@ -0,0 +1 @@
+import{_ as t,c as a,a5 as o,o as i}from"./chunks/framework.onQNwZ2I.js";const m=JSON.parse('{"title":"What is GeometryOps.jl?","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}'),n={name:"index.md"};function s(r,e,l,c,d,h){return i(),a("div",null,e[0]||(e[0]=[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!
GeometryOps' docs are divided into three main sections: tutorials, explanations and source code. Documentation and examples for many functions can be found in the source code section, since we use literate programming in GeometryOps.
Tutorials are meant to teach the fundamental concepts behind GeometryOps, and how to perform certain operations.
Explanations usually contain little code, and explain in more detail how GeometryOps works.
Source code usually contains explanations and examples at the top of the page, followed by annotated source code from that file.
',2)]))}const u=t(n,[["render",s]]);export{m as __pageData,u as default};
diff --git a/previews/PR239/assets/index.md.C-gmTcRS.lean.js b/previews/PR239/assets/index.md.C-gmTcRS.lean.js
new file mode 100644
index 000000000..0fe9ce310
--- /dev/null
+++ b/previews/PR239/assets/index.md.C-gmTcRS.lean.js
@@ -0,0 +1 @@
+import{_ as t,c as a,a5 as o,o as i}from"./chunks/framework.onQNwZ2I.js";const m=JSON.parse('{"title":"What is GeometryOps.jl?","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}'),n={name:"index.md"};function s(r,e,l,c,d,h){return i(),a("div",null,e[0]||(e[0]=[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!
GeometryOps' docs are divided into three main sections: tutorials, explanations and source code. Documentation and examples for many functions can be found in the source code section, since we use literate programming in GeometryOps.
Tutorials are meant to teach the fundamental concepts behind GeometryOps, and how to perform certain operations.
Explanations usually contain little code, and explain in more detail how GeometryOps works.
Source code usually contains explanations and examples at the top of the page, followed by annotated source code from that file.
',2)]))}const u=t(n,[["render",s]]);export{m as __pageData,u as default};
diff --git a/previews/PR239/assets/inter-italic-cyrillic-ext.r48I6akx.woff2 b/previews/PR239/assets/inter-italic-cyrillic-ext.r48I6akx.woff2
new file mode 100644
index 000000000..b6b603d59
Binary files /dev/null and b/previews/PR239/assets/inter-italic-cyrillic-ext.r48I6akx.woff2 differ
diff --git a/previews/PR239/assets/inter-italic-cyrillic.By2_1cv3.woff2 b/previews/PR239/assets/inter-italic-cyrillic.By2_1cv3.woff2
new file mode 100644
index 000000000..def40a4f6
Binary files /dev/null and b/previews/PR239/assets/inter-italic-cyrillic.By2_1cv3.woff2 differ
diff --git a/previews/PR239/assets/inter-italic-greek-ext.1u6EdAuj.woff2 b/previews/PR239/assets/inter-italic-greek-ext.1u6EdAuj.woff2
new file mode 100644
index 000000000..e070c3d30
Binary files /dev/null and b/previews/PR239/assets/inter-italic-greek-ext.1u6EdAuj.woff2 differ
diff --git a/previews/PR239/assets/inter-italic-greek.DJ8dCoTZ.woff2 b/previews/PR239/assets/inter-italic-greek.DJ8dCoTZ.woff2
new file mode 100644
index 000000000..a3c16ca40
Binary files /dev/null and b/previews/PR239/assets/inter-italic-greek.DJ8dCoTZ.woff2 differ
diff --git a/previews/PR239/assets/inter-italic-latin-ext.CN1xVJS-.woff2 b/previews/PR239/assets/inter-italic-latin-ext.CN1xVJS-.woff2
new file mode 100644
index 000000000..2210a899e
Binary files /dev/null and b/previews/PR239/assets/inter-italic-latin-ext.CN1xVJS-.woff2 differ
diff --git a/previews/PR239/assets/inter-italic-latin.C2AdPX0b.woff2 b/previews/PR239/assets/inter-italic-latin.C2AdPX0b.woff2
new file mode 100644
index 000000000..790d62dc7
Binary files /dev/null and b/previews/PR239/assets/inter-italic-latin.C2AdPX0b.woff2 differ
diff --git a/previews/PR239/assets/inter-italic-vietnamese.BSbpV94h.woff2 b/previews/PR239/assets/inter-italic-vietnamese.BSbpV94h.woff2
new file mode 100644
index 000000000..1eec0775a
Binary files /dev/null and b/previews/PR239/assets/inter-italic-vietnamese.BSbpV94h.woff2 differ
diff --git a/previews/PR239/assets/inter-roman-cyrillic-ext.BBPuwvHQ.woff2 b/previews/PR239/assets/inter-roman-cyrillic-ext.BBPuwvHQ.woff2
new file mode 100644
index 000000000..2cfe61536
Binary files /dev/null and b/previews/PR239/assets/inter-roman-cyrillic-ext.BBPuwvHQ.woff2 differ
diff --git a/previews/PR239/assets/inter-roman-cyrillic.C5lxZ8CY.woff2 b/previews/PR239/assets/inter-roman-cyrillic.C5lxZ8CY.woff2
new file mode 100644
index 000000000..e3886dd14
Binary files /dev/null and b/previews/PR239/assets/inter-roman-cyrillic.C5lxZ8CY.woff2 differ
diff --git a/previews/PR239/assets/inter-roman-greek-ext.CqjqNYQ-.woff2 b/previews/PR239/assets/inter-roman-greek-ext.CqjqNYQ-.woff2
new file mode 100644
index 000000000..36d67487d
Binary files /dev/null and b/previews/PR239/assets/inter-roman-greek-ext.CqjqNYQ-.woff2 differ
diff --git a/previews/PR239/assets/inter-roman-greek.BBVDIX6e.woff2 b/previews/PR239/assets/inter-roman-greek.BBVDIX6e.woff2
new file mode 100644
index 000000000..2bed1e85e
Binary files /dev/null and b/previews/PR239/assets/inter-roman-greek.BBVDIX6e.woff2 differ
diff --git a/previews/PR239/assets/inter-roman-latin-ext.4ZJIpNVo.woff2 b/previews/PR239/assets/inter-roman-latin-ext.4ZJIpNVo.woff2
new file mode 100644
index 000000000..9a8d1e2b5
Binary files /dev/null and b/previews/PR239/assets/inter-roman-latin-ext.4ZJIpNVo.woff2 differ
diff --git a/previews/PR239/assets/inter-roman-latin.Di8DUHzh.woff2 b/previews/PR239/assets/inter-roman-latin.Di8DUHzh.woff2
new file mode 100644
index 000000000..07d3c53ae
Binary files /dev/null and b/previews/PR239/assets/inter-roman-latin.Di8DUHzh.woff2 differ
diff --git a/previews/PR239/assets/inter-roman-vietnamese.BjW4sHH5.woff2 b/previews/PR239/assets/inter-roman-vietnamese.BjW4sHH5.woff2
new file mode 100644
index 000000000..57bdc22ae
Binary files /dev/null and b/previews/PR239/assets/inter-roman-vietnamese.BjW4sHH5.woff2 differ
diff --git a/previews/PR239/assets/introduction.md.FQTtykEQ.js b/previews/PR239/assets/introduction.md.FQTtykEQ.js
new file mode 100644
index 000000000..68fcb53ae
--- /dev/null
+++ b/previews/PR239/assets/introduction.md.FQTtykEQ.js
@@ -0,0 +1 @@
+import{_ as a,c as t,a5 as o,o as i}from"./chunks/framework.onQNwZ2I.js";const m=JSON.parse('{"title":"Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"introduction.md","filePath":"introduction.md","lastUpdated":null}'),r={name:"introduction.md"};function n(c,e,s,p,l,d){return i(),t("div",null,e[0]||(e[0]=[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)]))}const u=a(r,[["render",n]]);export{m as __pageData,u as default};
diff --git a/previews/PR239/assets/introduction.md.FQTtykEQ.lean.js b/previews/PR239/assets/introduction.md.FQTtykEQ.lean.js
new file mode 100644
index 000000000..68fcb53ae
--- /dev/null
+++ b/previews/PR239/assets/introduction.md.FQTtykEQ.lean.js
@@ -0,0 +1 @@
+import{_ as a,c as t,a5 as o,o as i}from"./chunks/framework.onQNwZ2I.js";const m=JSON.parse('{"title":"Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"introduction.md","filePath":"introduction.md","lastUpdated":null}'),r={name:"introduction.md"};function n(c,e,s,p,l,d){return i(),t("div",null,e[0]||(e[0]=[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!
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)]))}const o=i(t,[["render",h]]);export{g as __pageData,o as default};
diff --git a/previews/PR239/assets/source_GeometryOps.md.D_V6MfpH.lean.js b/previews/PR239/assets/source_GeometryOps.md.D_V6MfpH.lean.js
new file mode 100644
index 000000000..363b65baa
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOps.md.D_V6MfpH.lean.js
@@ -0,0 +1,85 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"GeometryOps.jl","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOps.md","filePath":"source/GeometryOps.md","lastUpdated":null}'),t={name:"source/GeometryOps.md"};function h(p,s,k,e,E,r){return l(),a("div",null,s[0]||(s[0]=[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)]))}const o=i(t,[["render",h]]);export{g as __pageData,o as default};
diff --git a/previews/PR239/assets/source_GeometryOpsFlexiJoinsExt_GeometryOpsFlexiJoinsExt.md.BtiH8and.js b/previews/PR239/assets/source_GeometryOpsFlexiJoinsExt_GeometryOpsFlexiJoinsExt.md.BtiH8and.js
new file mode 100644
index 000000000..88f619662
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsFlexiJoinsExt_GeometryOpsFlexiJoinsExt.md.BtiH8and.js
@@ -0,0 +1,16 @@
+import{_ as i,c as a,a5 as h,o as t}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsFlexiJoinsExt/GeometryOpsFlexiJoinsExt.md","filePath":"source/GeometryOpsFlexiJoinsExt/GeometryOpsFlexiJoinsExt.md","lastUpdated":null}'),n={name:"source/GeometryOpsFlexiJoinsExt/GeometryOpsFlexiJoinsExt.md"};function e(k,s,p,l,d,r){return t(),a("div",null,s[0]||(s[0]=[h(`
julia
module GeometryOpsFlexiJoinsExt
+
+using GeometryOps
+using FlexiJoins
+
+import GeometryOps as GO, GeoInterface as GI
+using SortTileRecursiveTree, Tables
This module defines the FlexiJoins APIs for GeometryOps' boolean comparison functions, taken from DE-9IM.
First, we define the joining modes (Tree, NestedLoopFast) that the GO DE-9IM functions support.
FlexiJoins.supports_mode(::FlexiJoins.Mode.NestedLoopFast, ::FlexiJoins.ByPred{F}, datas) where F <: GO_DE9IM_FUNCS = true
This method allows you to cache a tree, which we do by using an STRtree. TODO: wrap GO predicate functions in a TreeJoiner struct or something, to indicate that we want to use trees, since they can be slower in some situations.
julia
FlexiJoins.supports_mode(::FlexiJoins.Mode.Tree, ::FlexiJoins.ByPred{F}, datas) where F <: GO_DE9IM_FUNCS = true
Nested loop support is simple, and needs no further support. However, for trees, we need to define how the tree is prepared and how it is used. This is done by defining the prepare_for_join function to return an STRTree, and by defining the findmatchix function as querying that tree before checking intersections.
In theory, one could extract the tree from e.g a GeoPackage or some future GeoDataFrame.
julia
FlexiJoins.prepare_for_join(::FlexiJoins.Mode.Tree, X, cond::FlexiJoins.ByPred{<: GO_DE9IM_FUNCS}) = (X, SortTileRecursiveTree.STRtree(map(cond.Rf, X)))
+function FlexiJoins.findmatchix(::FlexiJoins.Mode.Tree, cond::FlexiJoins.ByPred{F}, ix_a, a, (B, tree)::Tuple, multi::typeof(identity)) where F <: GO_DE9IM_FUNCS
Implementation note: here, a is a row, and b is the full table. We extract the relevant columns using cond.Lf and cond.Rf.
julia
idxs = SortTileRecursiveTree.query(tree, cond.Lf(a))
+ intersecting_idxs = filter!(idxs) do idx
+ cond.pred(cond.Lf(a), cond.Rf(B[idx]))
+ end
+ return intersecting_idxs
+end
Finally, for completeness, we define the swap_sides function for those predicates which are defined as inversions.
`,19)]))}const y=i(n,[["render",e]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_GeometryOpsFlexiJoinsExt_GeometryOpsFlexiJoinsExt.md.BtiH8and.lean.js b/previews/PR239/assets/source_GeometryOpsFlexiJoinsExt_GeometryOpsFlexiJoinsExt.md.BtiH8and.lean.js
new file mode 100644
index 000000000..88f619662
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsFlexiJoinsExt_GeometryOpsFlexiJoinsExt.md.BtiH8and.lean.js
@@ -0,0 +1,16 @@
+import{_ as i,c as a,a5 as h,o as t}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsFlexiJoinsExt/GeometryOpsFlexiJoinsExt.md","filePath":"source/GeometryOpsFlexiJoinsExt/GeometryOpsFlexiJoinsExt.md","lastUpdated":null}'),n={name:"source/GeometryOpsFlexiJoinsExt/GeometryOpsFlexiJoinsExt.md"};function e(k,s,p,l,d,r){return t(),a("div",null,s[0]||(s[0]=[h(`
julia
module GeometryOpsFlexiJoinsExt
+
+using GeometryOps
+using FlexiJoins
+
+import GeometryOps as GO, GeoInterface as GI
+using SortTileRecursiveTree, Tables
This module defines the FlexiJoins APIs for GeometryOps' boolean comparison functions, taken from DE-9IM.
First, we define the joining modes (Tree, NestedLoopFast) that the GO DE-9IM functions support.
FlexiJoins.supports_mode(::FlexiJoins.Mode.NestedLoopFast, ::FlexiJoins.ByPred{F}, datas) where F <: GO_DE9IM_FUNCS = true
This method allows you to cache a tree, which we do by using an STRtree. TODO: wrap GO predicate functions in a TreeJoiner struct or something, to indicate that we want to use trees, since they can be slower in some situations.
julia
FlexiJoins.supports_mode(::FlexiJoins.Mode.Tree, ::FlexiJoins.ByPred{F}, datas) where F <: GO_DE9IM_FUNCS = true
Nested loop support is simple, and needs no further support. However, for trees, we need to define how the tree is prepared and how it is used. This is done by defining the prepare_for_join function to return an STRTree, and by defining the findmatchix function as querying that tree before checking intersections.
In theory, one could extract the tree from e.g a GeoPackage or some future GeoDataFrame.
julia
FlexiJoins.prepare_for_join(::FlexiJoins.Mode.Tree, X, cond::FlexiJoins.ByPred{<: GO_DE9IM_FUNCS}) = (X, SortTileRecursiveTree.STRtree(map(cond.Rf, X)))
+function FlexiJoins.findmatchix(::FlexiJoins.Mode.Tree, cond::FlexiJoins.ByPred{F}, ix_a, a, (B, tree)::Tuple, multi::typeof(identity)) where F <: GO_DE9IM_FUNCS
Implementation note: here, a is a row, and b is the full table. We extract the relevant columns using cond.Lf and cond.Rf.
julia
idxs = SortTileRecursiveTree.query(tree, cond.Lf(a))
+ intersecting_idxs = filter!(idxs) do idx
+ cond.pred(cond.Lf(a), cond.Rf(B[idx]))
+ end
+ return intersecting_idxs
+end
Finally, for completeness, we define the swap_sides function for those predicates which are defined as inversions.
`,19)]))}const y=i(n,[["render",e]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_GeometryOpsLibGEOSExt_GeometryOpsLibGEOSExt.md.BX97MBsi.js b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_GeometryOpsLibGEOSExt.md.BX97MBsi.js
new file mode 100644
index 000000000..2f1f59f92
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_GeometryOpsLibGEOSExt.md.BX97MBsi.js
@@ -0,0 +1,31 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const o=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsLibGEOSExt/GeometryOpsLibGEOSExt.md","filePath":"source/GeometryOpsLibGEOSExt/GeometryOpsLibGEOSExt.md","lastUpdated":null}'),e={name:"source/GeometryOpsLibGEOSExt/GeometryOpsLibGEOSExt.md"};function l(h,s,p,k,r,E){return t(),a("div",null,s[0]||(s[0]=[n(`
julia
module GeometryOpsLibGEOSExt
+
+import GeometryOps as GO, LibGEOS as LG
+import GeoInterface as GI
+
+import GeometryOps: GEOS, enforce, _True, _False, _booltype
+
+using GeometryOps
The filter statement is required because in Julia, each module has its own versions of these functions, which serve to evaluate or include code inside the scope of the module. However, if you import those from another module (which you would with all=true), that creates an ambiguity which causes a warning during precompile/load time. In order to avoid this, we filter out these special functions.
julia
for name in filter(!in((:var"#eval", :eval, :var"#include", :include)), names(GeometryOps))
+ @eval import GeometryOps: $name
+end
+
+"""
+ _wrap(geom; crs, calc_extent)
+
+Wraps \`geom\` in a GI wrapper geometry of its geometry trait. This allows us
+to attach CRS and extent info to geometry types which otherwise could not hold
+those, like LibGEOS and WKB geometries.
+
+Returns a GI wrapper geometry, for which \`parent(result) == geom\`.
+"""
+function _wrap(geom; crs=GI.crs(geom), calc_extent = true)
+ return GI.geointerface_geomtype(GI.geomtrait(geom))(geom; crs, extent = GI.extent(geom, calc_extent))
+end
+
+include("buffer.jl")
+include("segmentize.jl")
+include("simplify.jl")
+
+include("simple_overrides.jl")
+
+end
`,5)]))}const g=i(e,[["render",l]]);export{o as __pageData,g as default};
diff --git a/previews/PR239/assets/source_GeometryOpsLibGEOSExt_GeometryOpsLibGEOSExt.md.BX97MBsi.lean.js b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_GeometryOpsLibGEOSExt.md.BX97MBsi.lean.js
new file mode 100644
index 000000000..2f1f59f92
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_GeometryOpsLibGEOSExt.md.BX97MBsi.lean.js
@@ -0,0 +1,31 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const o=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsLibGEOSExt/GeometryOpsLibGEOSExt.md","filePath":"source/GeometryOpsLibGEOSExt/GeometryOpsLibGEOSExt.md","lastUpdated":null}'),e={name:"source/GeometryOpsLibGEOSExt/GeometryOpsLibGEOSExt.md"};function l(h,s,p,k,r,E){return t(),a("div",null,s[0]||(s[0]=[n(`
julia
module GeometryOpsLibGEOSExt
+
+import GeometryOps as GO, LibGEOS as LG
+import GeoInterface as GI
+
+import GeometryOps: GEOS, enforce, _True, _False, _booltype
+
+using GeometryOps
The filter statement is required because in Julia, each module has its own versions of these functions, which serve to evaluate or include code inside the scope of the module. However, if you import those from another module (which you would with all=true), that creates an ambiguity which causes a warning during precompile/load time. In order to avoid this, we filter out these special functions.
julia
for name in filter(!in((:var"#eval", :eval, :var"#include", :include)), names(GeometryOps))
+ @eval import GeometryOps: $name
+end
+
+"""
+ _wrap(geom; crs, calc_extent)
+
+Wraps \`geom\` in a GI wrapper geometry of its geometry trait. This allows us
+to attach CRS and extent info to geometry types which otherwise could not hold
+those, like LibGEOS and WKB geometries.
+
+Returns a GI wrapper geometry, for which \`parent(result) == geom\`.
+"""
+function _wrap(geom; crs=GI.crs(geom), calc_extent = true)
+ return GI.geointerface_geomtype(GI.geomtrait(geom))(geom; crs, extent = GI.extent(geom, calc_extent))
+end
+
+include("buffer.jl")
+include("segmentize.jl")
+include("simplify.jl")
+
+include("simple_overrides.jl")
+
+end
`,5)]))}const g=i(e,[["render",l]]);export{o as __pageData,g as default};
diff --git a/previews/PR239/assets/source_GeometryOpsLibGEOSExt_buffer.md.BIbTaNIz.js b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_buffer.md.BIbTaNIz.js
new file mode 100644
index 000000000..0703c9d6a
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_buffer.md.BIbTaNIz.js
@@ -0,0 +1,31 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const d=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsLibGEOSExt/buffer.md","filePath":"source/GeometryOpsLibGEOSExt/buffer.md","lastUpdated":null}'),k={name:"source/GeometryOpsLibGEOSExt/buffer.md"};function t(l,s,p,e,E,r){return h(),a("div",null,s[0]||(s[0]=[n(`
`,5)]))}const y=i(k,[["render",t]]);export{d as __pageData,y as default};
diff --git a/previews/PR239/assets/source_GeometryOpsLibGEOSExt_buffer.md.BIbTaNIz.lean.js b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_buffer.md.BIbTaNIz.lean.js
new file mode 100644
index 000000000..0703c9d6a
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_buffer.md.BIbTaNIz.lean.js
@@ -0,0 +1,31 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const d=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsLibGEOSExt/buffer.md","filePath":"source/GeometryOpsLibGEOSExt/buffer.md","lastUpdated":null}'),k={name:"source/GeometryOpsLibGEOSExt/buffer.md"};function t(l,s,p,e,E,r){return h(),a("div",null,s[0]||(s[0]=[n(`
`,5)]))}const y=i(k,[["render",t]]);export{d as __pageData,y as default};
diff --git a/previews/PR239/assets/source_GeometryOpsLibGEOSExt_segmentize.md.C7teKqJd.js b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_segmentize.md.C7teKqJd.js
new file mode 100644
index 000000000..ecd9353d1
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_segmentize.md.C7teKqJd.js
@@ -0,0 +1,21 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Segmentize","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsLibGEOSExt/segmentize.md","filePath":"source/GeometryOpsLibGEOSExt/segmentize.md","lastUpdated":null}'),e={name:"source/GeometryOpsLibGEOSExt/segmentize.md"};function h(k,s,l,p,r,E){return t(),a("div",null,s[0]||(s[0]=[n(`
TODO: should this just be a target on GI.AbstractGeometryTrait()? But Geos doesn't support eg RectangleTrait Maybe we need an abstract trait GI.AbstractWKBGeomTrait?
`,11)]))}const y=i(e,[["render",h]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_GeometryOpsLibGEOSExt_segmentize.md.C7teKqJd.lean.js b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_segmentize.md.C7teKqJd.lean.js
new file mode 100644
index 000000000..ecd9353d1
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_segmentize.md.C7teKqJd.lean.js
@@ -0,0 +1,21 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Segmentize","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsLibGEOSExt/segmentize.md","filePath":"source/GeometryOpsLibGEOSExt/segmentize.md","lastUpdated":null}'),e={name:"source/GeometryOpsLibGEOSExt/segmentize.md"};function h(k,s,l,p,r,E){return t(),a("div",null,s[0]||(s[0]=[n(`
TODO: should this just be a target on GI.AbstractGeometryTrait()? But Geos doesn't support eg RectangleTrait Maybe we need an abstract trait GI.AbstractWKBGeomTrait?
`,11)]))}const y=i(e,[["render",h]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simple_overrides.md.PL-RH0TF.js b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simple_overrides.md.PL-RH0TF.js
new file mode 100644
index 000000000..821c4e635
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simple_overrides.md.PL-RH0TF.js
@@ -0,0 +1,46 @@
+import{_ as i,c as a,a5 as h,o as n}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Simple overrides","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsLibGEOSExt/simple_overrides.md","filePath":"source/GeometryOpsLibGEOSExt/simple_overrides.md","lastUpdated":null}'),t={name:"source/GeometryOpsLibGEOSExt/simple_overrides.md"};function k(l,s,e,p,r,d){return n(),a("div",null,s[0]||(s[0]=[h(`
This file contains simple overrides for GEOS, essentially only those functions which have direct counterparts in LG and only require conversion before calling.
`,36)]))}const o=i(t,[["render",k]]);export{g as __pageData,o as default};
diff --git a/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simple_overrides.md.PL-RH0TF.lean.js b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simple_overrides.md.PL-RH0TF.lean.js
new file mode 100644
index 000000000..821c4e635
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simple_overrides.md.PL-RH0TF.lean.js
@@ -0,0 +1,46 @@
+import{_ as i,c as a,a5 as h,o as n}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Simple overrides","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsLibGEOSExt/simple_overrides.md","filePath":"source/GeometryOpsLibGEOSExt/simple_overrides.md","lastUpdated":null}'),t={name:"source/GeometryOpsLibGEOSExt/simple_overrides.md"};function k(l,s,e,p,r,d){return n(),a("div",null,s[0]||(s[0]=[h(`
This file contains simple overrides for GEOS, essentially only those functions which have direct counterparts in LG and only require conversion before calling.
`,36)]))}const o=i(t,[["render",k]]);export{g as __pageData,o as default};
diff --git a/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simplify.md.DqcZcvcS.js b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simplify.md.DqcZcvcS.js
new file mode 100644
index 000000000..fb6d1f2ff
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simplify.md.DqcZcvcS.js
@@ -0,0 +1,29 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsLibGEOSExt/simplify.md","filePath":"source/GeometryOpsLibGEOSExt/simplify.md","lastUpdated":null}'),k={name:"source/GeometryOpsLibGEOSExt/simplify.md"};function l(t,s,p,e,E,r){return h(),a("div",null,s[0]||(s[0]=[n(`
Address potential ambiguities
julia
GO._simplify(::GI.PointTrait, ::GO.GEOS, geom; kw...) = geom
+GO._simplify(::GI.MultiPointTrait, ::GO.GEOS, geom; kw...) = geom
+
+function GO._simplify(::GI.AbstractGeometryTrait, alg::GO.GEOS, geom; kwargs...)
+ method = get(alg, :method, :TopologyPreserve)
+ @assert haskey(alg.params, :tol) """
+ The \`:tol\` parameter is required for the GEOS algorithm in \`simplify\`,
+ but it was not provided.
+
+ Provide it by passing \`GEOS(; tol = ...,) as the algorithm.
+ """
+ tol = alg.params.tol
+ if method == :TopologyPreserve
+ return LG.topologyPreserveSimplify(GI.convert(LG, geom), tol)
+ elseif method == :DouglasPeucker
+ return LG.simplify(GI.convert(LG, geom), tol)
+ else
+ error("Invalid method passed to \`GO.simplify(GEOS(...), ...)\`: $method. Please use :TopologyPreserve or :DouglasPeucker")
+ end
+end
+
+function GO._simplify(trait::GI.AbstractCurveTrait, alg::GO.GEOS, geom; kw...)
+ Base.invoke(
+ GO._simplify,
+ Tuple{GI.AbstractGeometryTrait, GO.GEOS, typeof(geom)},
+ trait, alg, geom;
+ kw...
+ )
+end
`,4)]))}const y=i(k,[["render",l]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simplify.md.DqcZcvcS.lean.js b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simplify.md.DqcZcvcS.lean.js
new file mode 100644
index 000000000..fb6d1f2ff
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsLibGEOSExt_simplify.md.DqcZcvcS.lean.js
@@ -0,0 +1,29 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsLibGEOSExt/simplify.md","filePath":"source/GeometryOpsLibGEOSExt/simplify.md","lastUpdated":null}'),k={name:"source/GeometryOpsLibGEOSExt/simplify.md"};function l(t,s,p,e,E,r){return h(),a("div",null,s[0]||(s[0]=[n(`
Address potential ambiguities
julia
GO._simplify(::GI.PointTrait, ::GO.GEOS, geom; kw...) = geom
+GO._simplify(::GI.MultiPointTrait, ::GO.GEOS, geom; kw...) = geom
+
+function GO._simplify(::GI.AbstractGeometryTrait, alg::GO.GEOS, geom; kwargs...)
+ method = get(alg, :method, :TopologyPreserve)
+ @assert haskey(alg.params, :tol) """
+ The \`:tol\` parameter is required for the GEOS algorithm in \`simplify\`,
+ but it was not provided.
+
+ Provide it by passing \`GEOS(; tol = ...,) as the algorithm.
+ """
+ tol = alg.params.tol
+ if method == :TopologyPreserve
+ return LG.topologyPreserveSimplify(GI.convert(LG, geom), tol)
+ elseif method == :DouglasPeucker
+ return LG.simplify(GI.convert(LG, geom), tol)
+ else
+ error("Invalid method passed to \`GO.simplify(GEOS(...), ...)\`: $method. Please use :TopologyPreserve or :DouglasPeucker")
+ end
+end
+
+function GO._simplify(trait::GI.AbstractCurveTrait, alg::GO.GEOS, geom; kw...)
+ Base.invoke(
+ GO._simplify,
+ Tuple{GI.AbstractGeometryTrait, GO.GEOS, typeof(geom)},
+ trait, alg, geom;
+ kw...
+ )
+end
`,4)]))}const y=i(k,[["render",l]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_GeometryOpsProjExt_GeometryOpsProjExt.md.CF-5wcua.js b/previews/PR239/assets/source_GeometryOpsProjExt_GeometryOpsProjExt.md.CF-5wcua.js
new file mode 100644
index 000000000..7e3861f42
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsProjExt_GeometryOpsProjExt.md.CF-5wcua.js
@@ -0,0 +1,8 @@
+import{_ as e,c as a,a5 as i,o as t}from"./chunks/framework.onQNwZ2I.js";const c=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsProjExt/GeometryOpsProjExt.md","filePath":"source/GeometryOpsProjExt/GeometryOpsProjExt.md","lastUpdated":null}'),n={name:"source/GeometryOpsProjExt/GeometryOpsProjExt.md"};function p(l,s,r,o,h,k){return t(),a("div",null,s[0]||(s[0]=[i(`
`,3)]))}const E=e(n,[["render",p]]);export{c as __pageData,E as default};
diff --git a/previews/PR239/assets/source_GeometryOpsProjExt_GeometryOpsProjExt.md.CF-5wcua.lean.js b/previews/PR239/assets/source_GeometryOpsProjExt_GeometryOpsProjExt.md.CF-5wcua.lean.js
new file mode 100644
index 000000000..7e3861f42
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsProjExt_GeometryOpsProjExt.md.CF-5wcua.lean.js
@@ -0,0 +1,8 @@
+import{_ as e,c as a,a5 as i,o as t}from"./chunks/framework.onQNwZ2I.js";const c=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsProjExt/GeometryOpsProjExt.md","filePath":"source/GeometryOpsProjExt/GeometryOpsProjExt.md","lastUpdated":null}'),n={name:"source/GeometryOpsProjExt/GeometryOpsProjExt.md"};function p(l,s,r,o,h,k){return t(),a("div",null,s[0]||(s[0]=[i(`
`,3)]))}const E=e(n,[["render",p]]);export{c as __pageData,E as default};
diff --git a/previews/PR239/assets/source_GeometryOpsProjExt_reproject.md.Cm7Q7Ebj.js b/previews/PR239/assets/source_GeometryOpsProjExt_reproject.md.Cm7Q7Ebj.js
new file mode 100644
index 000000000..ffaa90130
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsProjExt_reproject.md.Cm7Q7Ebj.js
@@ -0,0 +1,44 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const d=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsProjExt/reproject.md","filePath":"source/GeometryOpsProjExt/reproject.md","lastUpdated":null}'),k={name:"source/GeometryOpsProjExt/reproject.md"};function t(p,s,l,e,r,E){return h(),a("div",null,s[0]||(s[0]=[n(`
julia
import GeometryOps: GI, GeoInterface, reproject, apply, transform, _is3d, _True, _False
+import Proj
+
+function reproject(geom;
+ source_crs=nothing, target_crs=nothing, transform=nothing, kw...
+)
+ if isnothing(transform)
+ if isnothing(source_crs)
+ source_crs = if GI.trait(geom) isa Nothing && geom isa AbstractArray
+ GeoInterface.crs(first(geom))
+ else
+ GeoInterface.crs(geom)
+ end
+ end
If its still nothing, error
julia
isnothing(source_crs) && throw(ArgumentError("geom has no crs attached. Pass a \`source_crs\` keyword"))
Otherwise reproject
julia
reproject(geom, source_crs, target_crs; kw...)
+ else
+ reproject(geom, transform; kw...)
+ end
+end
+function reproject(geom, source_crs, target_crs;
+ time=Inf,
+ always_xy=true,
+ transform=nothing,
+ kw...
+)
+ transform = if isnothing(transform)
+ s = source_crs isa Proj.CRS ? source_crs : convert(String, source_crs)
+ t = target_crs isa Proj.CRS ? target_crs : convert(String, target_crs)
+ Proj.Transformation(s, t; always_xy)
+ else
+ transform
+ end
+ reproject(geom, transform; time, target_crs, kw...)
+end
+function reproject(geom, transform::Proj.Transformation; time=Inf, target_crs=nothing, kw...)
+ if _is3d(geom)
+ return apply(GI.PointTrait(), geom; crs=target_crs, kw...) do p
+ transform(GI.x(p), GI.y(p), GI.z(p))
+ end
+ else
+ return apply(GI.PointTrait(), geom; crs=target_crs, kw...) do p
+ transform(GI.x(p), GI.y(p))
+ end
+ end
+end
`,7)]))}const y=i(k,[["render",t]]);export{d as __pageData,y as default};
diff --git a/previews/PR239/assets/source_GeometryOpsProjExt_reproject.md.Cm7Q7Ebj.lean.js b/previews/PR239/assets/source_GeometryOpsProjExt_reproject.md.Cm7Q7Ebj.lean.js
new file mode 100644
index 000000000..ffaa90130
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsProjExt_reproject.md.Cm7Q7Ebj.lean.js
@@ -0,0 +1,44 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const d=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsProjExt/reproject.md","filePath":"source/GeometryOpsProjExt/reproject.md","lastUpdated":null}'),k={name:"source/GeometryOpsProjExt/reproject.md"};function t(p,s,l,e,r,E){return h(),a("div",null,s[0]||(s[0]=[n(`
julia
import GeometryOps: GI, GeoInterface, reproject, apply, transform, _is3d, _True, _False
+import Proj
+
+function reproject(geom;
+ source_crs=nothing, target_crs=nothing, transform=nothing, kw...
+)
+ if isnothing(transform)
+ if isnothing(source_crs)
+ source_crs = if GI.trait(geom) isa Nothing && geom isa AbstractArray
+ GeoInterface.crs(first(geom))
+ else
+ GeoInterface.crs(geom)
+ end
+ end
If its still nothing, error
julia
isnothing(source_crs) && throw(ArgumentError("geom has no crs attached. Pass a \`source_crs\` keyword"))
Otherwise reproject
julia
reproject(geom, source_crs, target_crs; kw...)
+ else
+ reproject(geom, transform; kw...)
+ end
+end
+function reproject(geom, source_crs, target_crs;
+ time=Inf,
+ always_xy=true,
+ transform=nothing,
+ kw...
+)
+ transform = if isnothing(transform)
+ s = source_crs isa Proj.CRS ? source_crs : convert(String, source_crs)
+ t = target_crs isa Proj.CRS ? target_crs : convert(String, target_crs)
+ Proj.Transformation(s, t; always_xy)
+ else
+ transform
+ end
+ reproject(geom, transform; time, target_crs, kw...)
+end
+function reproject(geom, transform::Proj.Transformation; time=Inf, target_crs=nothing, kw...)
+ if _is3d(geom)
+ return apply(GI.PointTrait(), geom; crs=target_crs, kw...) do p
+ transform(GI.x(p), GI.y(p), GI.z(p))
+ end
+ else
+ return apply(GI.PointTrait(), geom; crs=target_crs, kw...) do p
+ transform(GI.x(p), GI.y(p))
+ end
+ end
+end
`,7)]))}const y=i(k,[["render",t]]);export{d as __pageData,y as default};
diff --git a/previews/PR239/assets/source_GeometryOpsProjExt_segmentize.md.DOG0-rtA.js b/previews/PR239/assets/source_GeometryOpsProjExt_segmentize.md.DOG0-rtA.js
new file mode 100644
index 000000000..92742bf54
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsProjExt_segmentize.md.DOG0-rtA.js
@@ -0,0 +1,31 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsProjExt/segmentize.md","filePath":"source/GeometryOpsProjExt/segmentize.md","lastUpdated":null}'),t={name:"source/GeometryOpsProjExt/segmentize.md"};function k(e,s,l,p,d,r){return h(),a("div",null,s[0]||(s[0]=[n(`
`,10)]))}const y=i(t,[["render",k]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_GeometryOpsProjExt_segmentize.md.DOG0-rtA.lean.js b/previews/PR239/assets/source_GeometryOpsProjExt_segmentize.md.DOG0-rtA.lean.js
new file mode 100644
index 000000000..92742bf54
--- /dev/null
+++ b/previews/PR239/assets/source_GeometryOpsProjExt_segmentize.md.DOG0-rtA.lean.js
@@ -0,0 +1,31 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/GeometryOpsProjExt/segmentize.md","filePath":"source/GeometryOpsProjExt/segmentize.md","lastUpdated":null}'),t={name:"source/GeometryOpsProjExt/segmentize.md"};function k(e,s,l,p,d,r){return h(),a("div",null,s[0]||(s[0]=[n(`
`,10)]))}const y=i(t,[["render",k]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_angles.md.B9lhXIGg.js b/previews/PR239/assets/source_methods_angles.md.B9lhXIGg.js
new file mode 100644
index 000000000..5c17fafc8
--- /dev/null
+++ b/previews/PR239/assets/source_methods_angles.md.B9lhXIGg.js
@@ -0,0 +1,124 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const l="/GeometryOps.jl/previews/PR239/assets/pkevosp.Dig-DWOQ.png",y=JSON.parse('{"title":"Angles","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/angles.md","filePath":"source/methods/angles.md","lastUpdated":null}'),k={name:"source/methods/angles.md"};function t(p,s,e,r,E,g){return h(),a("div",null,s[0]||(s[0]=[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 polygon 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 polygon, 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)]))}const F=i(k,[["render",t]]);export{y as __pageData,F as default};
diff --git a/previews/PR239/assets/source_methods_angles.md.B9lhXIGg.lean.js b/previews/PR239/assets/source_methods_angles.md.B9lhXIGg.lean.js
new file mode 100644
index 000000000..5c17fafc8
--- /dev/null
+++ b/previews/PR239/assets/source_methods_angles.md.B9lhXIGg.lean.js
@@ -0,0 +1,124 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const l="/GeometryOps.jl/previews/PR239/assets/pkevosp.Dig-DWOQ.png",y=JSON.parse('{"title":"Angles","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/angles.md","filePath":"source/methods/angles.md","lastUpdated":null}'),k={name:"source/methods/angles.md"};function t(p,s,e,r,E,g){return h(),a("div",null,s[0]||(s[0]=[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 polygon 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 polygon, 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)]))}const F=i(k,[["render",t]]);export{y as __pageData,F as default};
diff --git a/previews/PR239/assets/source_methods_area.md.42EUHlu6.js b/previews/PR239/assets/source_methods_area.md.42EUHlu6.js
new file mode 100644
index 000000000..f8c65c212
--- /dev/null
+++ b/previews/PR239/assets/source_methods_area.md.42EUHlu6.js
@@ -0,0 +1,87 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/pkevosp.Dig-DWOQ.png",e="/GeometryOps.jl/previews/PR239/assets/dytnfok.CULn5saZ.png",y=JSON.parse('{"title":"Area and signed area","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/area.md","filePath":"source/methods/area.md","lastUpdated":null}'),l={name:"source/methods/area.md"};function p(k,s,r,d,g,E){return h(),a("div",null,s[0]||(s[0]=[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 positive 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 slightly 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)]))}const F=i(l,[["render",p]]);export{y as __pageData,F as default};
diff --git a/previews/PR239/assets/source_methods_area.md.42EUHlu6.lean.js b/previews/PR239/assets/source_methods_area.md.42EUHlu6.lean.js
new file mode 100644
index 000000000..f8c65c212
--- /dev/null
+++ b/previews/PR239/assets/source_methods_area.md.42EUHlu6.lean.js
@@ -0,0 +1,87 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/pkevosp.Dig-DWOQ.png",e="/GeometryOps.jl/previews/PR239/assets/dytnfok.CULn5saZ.png",y=JSON.parse('{"title":"Area and signed area","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/area.md","filePath":"source/methods/area.md","lastUpdated":null}'),l={name:"source/methods/area.md"};function p(k,s,r,d,g,E){return h(),a("div",null,s[0]||(s[0]=[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 positive 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 slightly 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
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!
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!
`,35))])}const b=k(p,[["render",C]]);export{m as __pageData,b as default};
diff --git a/previews/PR239/assets/source_methods_buffer.md.Wvk7coQv.js b/previews/PR239/assets/source_methods_buffer.md.Wvk7coQv.js
new file mode 100644
index 000000000..dde6ba167
--- /dev/null
+++ b/previews/PR239/assets/source_methods_buffer.md.Wvk7coQv.js
@@ -0,0 +1,11 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Buffer","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/buffer.md","filePath":"source/methods/buffer.md","lastUpdated":null}'),e={name:"source/methods/buffer.md"};function h(k,s,p,l,r,d){return t(),a("div",null,s[0]||(s[0]=[n(`
Below is an error handler similar to the others we have for e.g. segmentize, which checks if there is a method error for the geos backend.
Add an error hint for buffer if LibGEOS is not loaded!
julia
function _buffer_error_hinter(io, exc, argtypes, kwargs)
+ if isnothing(Base.get_extension(GeometryOps, :GeometryOpsLibGEOSExt)) && exc.f == buffer && first(argtypes) == GEOS
+ print(io, "\\n\\nThe \`buffer\` method requires the LibGEOS.jl package to be explicitly loaded.\\n")
+ print(io, "You can do this by simply typing ")
+ printstyled(io, "using LibGEOS"; color = :cyan, bold = true)
+ println(io, " in your REPL, \\nor otherwise loading LibGEOS.jl via using or import.")
+ end
+end
`,9)]))}const o=i(e,[["render",h]]);export{g as __pageData,o as default};
diff --git a/previews/PR239/assets/source_methods_buffer.md.Wvk7coQv.lean.js b/previews/PR239/assets/source_methods_buffer.md.Wvk7coQv.lean.js
new file mode 100644
index 000000000..dde6ba167
--- /dev/null
+++ b/previews/PR239/assets/source_methods_buffer.md.Wvk7coQv.lean.js
@@ -0,0 +1,11 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Buffer","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/buffer.md","filePath":"source/methods/buffer.md","lastUpdated":null}'),e={name:"source/methods/buffer.md"};function h(k,s,p,l,r,d){return t(),a("div",null,s[0]||(s[0]=[n(`
Below is an error handler similar to the others we have for e.g. segmentize, which checks if there is a method error for the geos backend.
Add an error hint for buffer if LibGEOS is not loaded!
julia
function _buffer_error_hinter(io, exc, argtypes, kwargs)
+ if isnothing(Base.get_extension(GeometryOps, :GeometryOpsLibGEOSExt)) && exc.f == buffer && first(argtypes) == GEOS
+ print(io, "\\n\\nThe \`buffer\` method requires the LibGEOS.jl package to be explicitly loaded.\\n")
+ print(io, "You can do this by simply typing ")
+ printstyled(io, "using LibGEOS"; color = :cyan, bold = true)
+ println(io, " in your REPL, \\nor otherwise loading LibGEOS.jl via using or import.")
+ end
+end
`,9)]))}const o=i(e,[["render",h]]);export{g as __pageData,o as default};
diff --git a/previews/PR239/assets/source_methods_centroid.md.CPAUzyVU.js b/previews/PR239/assets/source_methods_centroid.md.CPAUzyVU.js
new file mode 100644
index 000000000..32151a8fd
--- /dev/null
+++ b/previews/PR239/assets/source_methods_centroid.md.CPAUzyVU.js
@@ -0,0 +1,93 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/ibdeule.BD0hVfse.png",k="/GeometryOps.jl/previews/PR239/assets/cgnfnmo.DHcwB147.png",o=JSON.parse('{"title":"Centroid","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/centroid.md","filePath":"source/methods/centroid.md","lastUpdated":null}'),l={name:"source/methods/centroid.md"};function p(e,s,r,E,d,g){return h(),a("div",null,s[0]||(s[0]=[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 available 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)]))}const c=i(l,[["render",p]]);export{o as __pageData,c as default};
diff --git a/previews/PR239/assets/source_methods_centroid.md.CPAUzyVU.lean.js b/previews/PR239/assets/source_methods_centroid.md.CPAUzyVU.lean.js
new file mode 100644
index 000000000..32151a8fd
--- /dev/null
+++ b/previews/PR239/assets/source_methods_centroid.md.CPAUzyVU.lean.js
@@ -0,0 +1,93 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/ibdeule.BD0hVfse.png",k="/GeometryOps.jl/previews/PR239/assets/cgnfnmo.DHcwB147.png",o=JSON.parse('{"title":"Centroid","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/centroid.md","filePath":"source/methods/centroid.md","lastUpdated":null}'),l={name:"source/methods/centroid.md"};function p(e,s,r,E,d,g){return h(),a("div",null,s[0]||(s[0]=[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 available 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)]))}const c=i(l,[["render",p]]);export{o as __pageData,c as default};
diff --git a/previews/PR239/assets/source_methods_clipping_clipping_processor.md.Ci1IQvdb.js b/previews/PR239/assets/source_methods_clipping_clipping_processor.md.Ci1IQvdb.js
new file mode 100644
index 000000000..3ec0b2217
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_clipping_processor.md.Ci1IQvdb.js
@@ -0,0 +1,508 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const g=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}'),t={name:"source/methods/clipping/clipping_processor.md"};function p(l,s,k,e,E,r){return h(),a("div",null,s[0]||(s[0]=[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 indices 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 indices 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 neighbor 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 polygons with no crossing intersection points, either one polygon is inside of another, or they are separate 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
+ curr_hole = _linearring(curr_hole)
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 completely 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 completely 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 original 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 approximately 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)]))}const y=i(t,[["render",p]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_clipping_clipping_processor.md.Ci1IQvdb.lean.js b/previews/PR239/assets/source_methods_clipping_clipping_processor.md.Ci1IQvdb.lean.js
new file mode 100644
index 000000000..3ec0b2217
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_clipping_processor.md.Ci1IQvdb.lean.js
@@ -0,0 +1,508 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const g=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}'),t={name:"source/methods/clipping/clipping_processor.md"};function p(l,s,k,e,E,r){return h(),a("div",null,s[0]||(s[0]=[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 indices 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 indices 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 neighbor 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 polygons with no crossing intersection points, either one polygon is inside of another, or they are separate 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
+ curr_hole = _linearring(curr_hole)
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 completely 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 completely 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 original 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 approximately 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)]))}const y=i(t,[["render",p]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_clipping_coverage.md.C89Y2dMt.js b/previews/PR239/assets/source_methods_clipping_coverage.md.C89Y2dMt.js
new file mode 100644
index 000000000..bb2eab7c0
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_coverage.md.C89Y2dMt.js
@@ -0,0 +1,223 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const l="/GeometryOps.jl/previews/PR239/assets/kguctvv.Cb0_DiYE.png",y=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/coverage.md","filePath":"source/methods/clipping/coverage.md","lastUpdated":null}'),k={name:"source/methods/clipping/coverage.md"};function p(t,s,e,E,r,d){return h(),a("div",null,s[0]||(s[0]=[n(`
Coverage is the amount of geometry area within a bounding box defined by the minimum and maximum x and y-coordinates 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)]))}const F=i(k,[["render",p]]);export{y as __pageData,F as default};
diff --git a/previews/PR239/assets/source_methods_clipping_coverage.md.C89Y2dMt.lean.js b/previews/PR239/assets/source_methods_clipping_coverage.md.C89Y2dMt.lean.js
new file mode 100644
index 000000000..bb2eab7c0
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_coverage.md.C89Y2dMt.lean.js
@@ -0,0 +1,223 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const l="/GeometryOps.jl/previews/PR239/assets/kguctvv.Cb0_DiYE.png",y=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/coverage.md","filePath":"source/methods/clipping/coverage.md","lastUpdated":null}'),k={name:"source/methods/clipping/coverage.md"};function p(t,s,e,E,r,d){return h(),a("div",null,s[0]||(s[0]=[n(`
Coverage is the amount of geometry area within a bounding box defined by the minimum and maximum x and y-coordinates 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)]))}const F=i(k,[["render",p]]);export{y as __pageData,F as default};
diff --git a/previews/PR239/assets/source_methods_clipping_cut.md.D8NjrBmq.js b/previews/PR239/assets/source_methods_clipping_cut.md.D8NjrBmq.js
new file mode 100644
index 000000000..7d4d09979
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_cut.md.D8NjrBmq.js
@@ -0,0 +1,87 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/oafsxip.-VpeHhXX.png",y=JSON.parse('{"title":"Polygon cutting","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/cut.md","filePath":"source/methods/clipping/cut.md","lastUpdated":null}'),l={name:"source/methods/clipping/cut.md"};function p(k,s,e,r,E,d){return h(),a("div",null,s[0]||(s[0]=[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 categorize the intersection points
julia
sort!(intr_list, by = x -> geom_list[x].fracs[2])
+ _flag_ent_exit!(GI.LineTrait(), line, geom_list; exact)
`,34)]))}const o=i(l,[["render",p]]);export{y as __pageData,o as default};
diff --git a/previews/PR239/assets/source_methods_clipping_cut.md.D8NjrBmq.lean.js b/previews/PR239/assets/source_methods_clipping_cut.md.D8NjrBmq.lean.js
new file mode 100644
index 000000000..7d4d09979
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_cut.md.D8NjrBmq.lean.js
@@ -0,0 +1,87 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/oafsxip.-VpeHhXX.png",y=JSON.parse('{"title":"Polygon cutting","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/cut.md","filePath":"source/methods/clipping/cut.md","lastUpdated":null}'),l={name:"source/methods/clipping/cut.md"};function p(k,s,e,r,E,d){return h(),a("div",null,s[0]||(s[0]=[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 categorize the intersection points
julia
sort!(intr_list, by = x -> geom_list[x].fracs[2])
+ _flag_ent_exit!(GI.LineTrait(), line, geom_list; exact)
`,34)]))}const o=i(l,[["render",p]]);export{y as __pageData,o as default};
diff --git a/previews/PR239/assets/source_methods_clipping_difference.md.KRJn9sdE.js b/previews/PR239/assets/source_methods_clipping_difference.md.KRJn9sdE.js
new file mode 100644
index 000000000..68fd9cebd
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_difference.md.KRJn9sdE.js
@@ -0,0 +1,166 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const y=JSON.parse('{"title":"Difference Polygon Clipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/difference.md","filePath":"source/methods/clipping/difference.md","lastUpdated":null}'),p={name:"source/methods/clipping/difference.md"};function t(h,s,e,k,r,d){return l(),a("div",null,s[0]||(s[0]=[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 (default 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))
+ #= Removing intersections of \`multipoly_a\`\` with pieces of \`multipoly_b\`\` - as
+ pieces of \`multipolygon_a\`\` are removed, continue to take difference with new shape
+ \`polys\` =#
+ polys = if i == 1
+ difference(multipoly_a, poly_b; target, fix_multipoly)
+ else
+ difference(GI.MultiPolygon(polys), poly_b; target, fix_multipoly)
+ end
+ #= One multipoly_a has been completely covered (and thus removed) there is no need to
+ continue taking the difference =#
+ isempty(polys) && break
+ 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)]))}const E=i(p,[["render",t]]);export{y as __pageData,E as default};
diff --git a/previews/PR239/assets/source_methods_clipping_difference.md.KRJn9sdE.lean.js b/previews/PR239/assets/source_methods_clipping_difference.md.KRJn9sdE.lean.js
new file mode 100644
index 000000000..68fd9cebd
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_difference.md.KRJn9sdE.lean.js
@@ -0,0 +1,166 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const y=JSON.parse('{"title":"Difference Polygon Clipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/difference.md","filePath":"source/methods/clipping/difference.md","lastUpdated":null}'),p={name:"source/methods/clipping/difference.md"};function t(h,s,e,k,r,d){return l(),a("div",null,s[0]||(s[0]=[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 (default 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))
+ #= Removing intersections of \`multipoly_a\`\` with pieces of \`multipoly_b\`\` - as
+ pieces of \`multipolygon_a\`\` are removed, continue to take difference with new shape
+ \`polys\` =#
+ polys = if i == 1
+ difference(multipoly_a, poly_b; target, fix_multipoly)
+ else
+ difference(GI.MultiPolygon(polys), poly_b; target, fix_multipoly)
+ end
+ #= One multipoly_a has been completely covered (and thus removed) there is no need to
+ continue taking the difference =#
+ isempty(polys) && break
+ 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)]))}const E=i(p,[["render",t]]);export{y as __pageData,E as default};
diff --git a/previews/PR239/assets/source_methods_clipping_intersection.md.bcPofDGt.js b/previews/PR239/assets/source_methods_clipping_intersection.md.bcPofDGt.js
new file mode 100644
index 000000000..7d67e5afa
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_intersection.md.bcPofDGt.js
@@ -0,0 +1,383 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Geometry Intersection","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/intersection.md","filePath":"source/methods/clipping/intersection.md","lastUpdated":null}'),h={name:"source/methods/clipping/intersection.md"};function l(p,s,k,e,r,E){return t(),a("div",null,s[0]||(s[0]=[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\` (collinear 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
+polygon 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, [T::Type])
+
+Return a list of intersection tuple points between two geometries. If no intersection points
+exist, returns an empty list.
+
+# 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_points(line1, line2)
output
julia
1-element Vector{Tuple{Float64, Float64}}:
+ (125.58375366067548, -14.83572303404496)
+"""
+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, including line
+segments, line strings, linear rings, polygons, and multipolygons. =#
+function _intersection_points(::Type{T}, ::GI.AbstractTrait, a, ::GI.AbstractTrait, b; exact = _True()) where T
Initialize an empty list of points
julia
result = Tuple{T, T}[]
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
julia
edges_a, edges_b = map(sort! ∘ to_edges, (a, b))
Loop over pairs of edges and add any unique intersection points to results
julia
for a_edge in edges_a, b_edge in edges_b
+ line_orient, intr1, intr2 = _intersection_point(T, a_edge, b_edge; exact)
+ line_orient == line_out && continue # no intersection points
+ pt1, _ = intr1
+ push!(result, pt1) # if not line_out, there is at least one intersection point
+ if line_orient == line_over # if line_over, there are two intersection points
+ pt2, _ = intr2
+ push!(result, pt2)
+ end
+ end
+ #= TODO: We might be able to just add unique points with checks on the α and β values
+ returned from \`_intersection_point\`, but this would be different for curves vs polygons
+ vs multipolygons depending on if the shape is closed. This then wouldn't allow using the
+ \`to_edges\` functionality. =#
+ unique!(sort!(result))
+ 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 calculated 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
+ inaccuracies, α and β calculations may yield 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 certainly 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)]))}const y=i(h,[["render",l]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_clipping_intersection.md.bcPofDGt.lean.js b/previews/PR239/assets/source_methods_clipping_intersection.md.bcPofDGt.lean.js
new file mode 100644
index 000000000..7d67e5afa
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_intersection.md.bcPofDGt.lean.js
@@ -0,0 +1,383 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Geometry Intersection","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/intersection.md","filePath":"source/methods/clipping/intersection.md","lastUpdated":null}'),h={name:"source/methods/clipping/intersection.md"};function l(p,s,k,e,r,E){return t(),a("div",null,s[0]||(s[0]=[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\` (collinear 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
+polygon 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, [T::Type])
+
+Return a list of intersection tuple points between two geometries. If no intersection points
+exist, returns an empty list.
+
+# 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_points(line1, line2)
output
julia
1-element Vector{Tuple{Float64, Float64}}:
+ (125.58375366067548, -14.83572303404496)
+"""
+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, including line
+segments, line strings, linear rings, polygons, and multipolygons. =#
+function _intersection_points(::Type{T}, ::GI.AbstractTrait, a, ::GI.AbstractTrait, b; exact = _True()) where T
Initialize an empty list of points
julia
result = Tuple{T, T}[]
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
julia
edges_a, edges_b = map(sort! ∘ to_edges, (a, b))
Loop over pairs of edges and add any unique intersection points to results
julia
for a_edge in edges_a, b_edge in edges_b
+ line_orient, intr1, intr2 = _intersection_point(T, a_edge, b_edge; exact)
+ line_orient == line_out && continue # no intersection points
+ pt1, _ = intr1
+ push!(result, pt1) # if not line_out, there is at least one intersection point
+ if line_orient == line_over # if line_over, there are two intersection points
+ pt2, _ = intr2
+ push!(result, pt2)
+ end
+ end
+ #= TODO: We might be able to just add unique points with checks on the α and β values
+ returned from \`_intersection_point\`, but this would be different for curves vs polygons
+ vs multipolygons depending on if the shape is closed. This then wouldn't allow using the
+ \`to_edges\` functionality. =#
+ unique!(sort!(result))
+ 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 calculated 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
+ inaccuracies, α and β calculations may yield 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 certainly 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)]))}const y=i(h,[["render",l]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_clipping_predicates.md.BJITr_Uq.js b/previews/PR239/assets/source_methods_clipping_predicates.md.BJITr_Uq.js
new file mode 100644
index 000000000..3e7fbf706
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_predicates.md.BJITr_Uq.js
@@ -0,0 +1,44 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const c=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}'),h={name:"source/methods/clipping/predicates.md"};function e(p,s,l,k,r,d){return t(),a("div",null,s[0]||(s[0]=[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)]))}const g=i(h,[["render",e]]);export{c as __pageData,g as default};
diff --git a/previews/PR239/assets/source_methods_clipping_predicates.md.BJITr_Uq.lean.js b/previews/PR239/assets/source_methods_clipping_predicates.md.BJITr_Uq.lean.js
new file mode 100644
index 000000000..3e7fbf706
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_predicates.md.BJITr_Uq.lean.js
@@ -0,0 +1,44 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const c=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}'),h={name:"source/methods/clipping/predicates.md"};function e(p,s,l,k,r,d){return t(),a("div",null,s[0]||(s[0]=[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)]))}const g=i(h,[["render",e]]);export{c as __pageData,g as default};
diff --git a/previews/PR239/assets/source_methods_clipping_union.md.DlTyWPn1.js b/previews/PR239/assets/source_methods_clipping_union.md.DlTyWPn1.js
new file mode 100644
index 000000000..ecc318c2a
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_union.md.DlTyWPn1.js
@@ -0,0 +1,251 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const y=JSON.parse('{"title":"Union Polygon Clipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/union.md","filePath":"source/methods/clipping/union.md","lastUpdated":null}'),h={name:"source/methods/clipping/union.md"};function p(t,s,k,e,r,E){return l(),a("div",null,s[0]||(s[0]=[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([_linearring(tuples(ext_b))]))
+ elseif b_in_a
+ push!(polys, GI.Polygon([_linearring(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))))
+ ih = _linearring(ih)
+ 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 completely 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 polygon 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)]))}const d=i(h,[["render",p]]);export{y as __pageData,d as default};
diff --git a/previews/PR239/assets/source_methods_clipping_union.md.DlTyWPn1.lean.js b/previews/PR239/assets/source_methods_clipping_union.md.DlTyWPn1.lean.js
new file mode 100644
index 000000000..ecc318c2a
--- /dev/null
+++ b/previews/PR239/assets/source_methods_clipping_union.md.DlTyWPn1.lean.js
@@ -0,0 +1,251 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const y=JSON.parse('{"title":"Union Polygon Clipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/clipping/union.md","filePath":"source/methods/clipping/union.md","lastUpdated":null}'),h={name:"source/methods/clipping/union.md"};function p(t,s,k,e,r,E){return l(),a("div",null,s[0]||(s[0]=[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([_linearring(tuples(ext_b))]))
+ elseif b_in_a
+ push!(polys, GI.Polygon([_linearring(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))))
+ ih = _linearring(ih)
+ 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 completely 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 polygon 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)]))}const d=i(h,[["render",p]]);export{y as __pageData,d as default};
diff --git a/previews/PR239/assets/source_methods_convex_hull.md.DkVMD0Lv.js b/previews/PR239/assets/source_methods_convex_hull.md.DkVMD0Lv.js
new file mode 100644
index 000000000..10d5d100a
--- /dev/null
+++ b/previews/PR239/assets/source_methods_convex_hull.md.DkVMD0Lv.js
@@ -0,0 +1,57 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/kbbskga.BT_oJ_KS.png",h="/GeometryOps.jl/previews/PR239/assets/filtvpm.mCtKcWOr.png",e="/GeometryOps.jl/previews/PR239/assets/cvdrlht.HTM0ungm.png",c=JSON.parse('{"title":"Convex hull","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/convex_hull.md","filePath":"source/methods/convex_hull.md","lastUpdated":null}'),p={name:"source/methods/convex_hull.md"};function k(r,s,o,d,E,g){return l(),a("div",null,s[0]||(s[0]=[n(`
The convex hull of a set of points is the smallest convex polygon that contains all the points.
GeometryOps.jl provides a number of methods for computing the convex hull of a set of points, usually linked to other Julia packages.
For now, we expose one algorithm, MonotoneChainMethod, which uses the DelaunayTriangulation.jl package. The GEOS() interface also supports convex hulls.
Future work could include other algorithms, such as Quickhull.jl, or similar, via package extensions.
import GeometryOps as GO, GeoInterface as GI
+using CairoMakie # to plot
+using NaturalEarth # for data
+
+all_adm0 = naturalearth("admin_0_countries", 110)
+usa = all_adm0.geometry[findfirst(==("USA"), all_adm0.ADM0_A3)]
+f, a, p = lines(usa)
+lines!(a, GO.convex_hull(usa); color = Makie.wong_colors()[2])
+f
The winding order of the monotone chain method is counterclockwise, while the winding order of the GEOS method is clockwise.
GeometryOps' convexity detection says that the GEOS hull is convex, while the monotone chain method hull is not. However, they are both going over the same points (we checked), it's just that the winding order is different.
In reality, both sets are convex, but we need to fix the GeometryOps convexity detector (isconcave)!
We may also decide at a later date to change the returned winding order of the polygon, but most algorithms are robust to that, and you can always fix it...
julia
import GeoInterface as GI, GeometryOps as GO, LibGEOS as LG
+using CairoMakie # to plot
+
+points = rand(Point2{Float64}, 100)
+go_hull = GO.convex_hull(GO.MonotoneChainMethod(), points)
+lg_hull = GO.convex_hull(GO.GEOS(), points)
+
+fig = Figure()
+a1, p1 = lines(fig[1, 1], go_hull; color = 1:GI.npoint(go_hull), axis = (; title = "MonotoneChainMethod()"))
+a2, p2 = lines(fig[2, 1], lg_hull; color = 1:GI.npoint(lg_hull), axis = (; title = "GEOS()"))
+cb = Colorbar(fig[1:2, 2], p1; label = "Vertex number")
+fig
"""
+ convex_hull([method], geometries)
+
+Compute the convex hull of the points in \`geometries\`.
+Returns a \`GI.Polygon\` representing the convex hull.
+
+Note that the polygon returned is wound counterclockwise
+as in the Simple Features standard by default. If you
+choose GEOS, the winding order will be inverted.
+
+!!! warning
+ This interface only computes the 2-dimensional convex hull!
+
+ For higher dimensional hulls, use the relevant package (Qhull.jl, Quickhull.jl, or similar).
+"""
+function convex_hull end
+
+"""
+ MonotoneChainMethod()
+
+This is an algorithm for the \`convex_hull\` function.
+
+Uses [\`DelaunayTriangulation.jl\`](https://github.com/JuliaGeometry/DelaunayTriangulation.jl) to compute the convex hull.
+This is a pure Julia algorithm which provides an optimal Delaunay triangulation.
+
+See also \`convex_hull\`
+"""
+struct MonotoneChainMethod end
GrahamScanMethod, etc. can be implemented in GO as well, if someone wants to. If we add an extension on Quickhull.jl, then that would be another algorithm.
`,35)]))}const u=i(p,[["render",k]]);export{c as __pageData,u as default};
diff --git a/previews/PR239/assets/source_methods_convex_hull.md.DkVMD0Lv.lean.js b/previews/PR239/assets/source_methods_convex_hull.md.DkVMD0Lv.lean.js
new file mode 100644
index 000000000..10d5d100a
--- /dev/null
+++ b/previews/PR239/assets/source_methods_convex_hull.md.DkVMD0Lv.lean.js
@@ -0,0 +1,57 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/kbbskga.BT_oJ_KS.png",h="/GeometryOps.jl/previews/PR239/assets/filtvpm.mCtKcWOr.png",e="/GeometryOps.jl/previews/PR239/assets/cvdrlht.HTM0ungm.png",c=JSON.parse('{"title":"Convex hull","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/convex_hull.md","filePath":"source/methods/convex_hull.md","lastUpdated":null}'),p={name:"source/methods/convex_hull.md"};function k(r,s,o,d,E,g){return l(),a("div",null,s[0]||(s[0]=[n(`
The convex hull of a set of points is the smallest convex polygon that contains all the points.
GeometryOps.jl provides a number of methods for computing the convex hull of a set of points, usually linked to other Julia packages.
For now, we expose one algorithm, MonotoneChainMethod, which uses the DelaunayTriangulation.jl package. The GEOS() interface also supports convex hulls.
Future work could include other algorithms, such as Quickhull.jl, or similar, via package extensions.
import GeometryOps as GO, GeoInterface as GI
+using CairoMakie # to plot
+using NaturalEarth # for data
+
+all_adm0 = naturalearth("admin_0_countries", 110)
+usa = all_adm0.geometry[findfirst(==("USA"), all_adm0.ADM0_A3)]
+f, a, p = lines(usa)
+lines!(a, GO.convex_hull(usa); color = Makie.wong_colors()[2])
+f
The winding order of the monotone chain method is counterclockwise, while the winding order of the GEOS method is clockwise.
GeometryOps' convexity detection says that the GEOS hull is convex, while the monotone chain method hull is not. However, they are both going over the same points (we checked), it's just that the winding order is different.
In reality, both sets are convex, but we need to fix the GeometryOps convexity detector (isconcave)!
We may also decide at a later date to change the returned winding order of the polygon, but most algorithms are robust to that, and you can always fix it...
julia
import GeoInterface as GI, GeometryOps as GO, LibGEOS as LG
+using CairoMakie # to plot
+
+points = rand(Point2{Float64}, 100)
+go_hull = GO.convex_hull(GO.MonotoneChainMethod(), points)
+lg_hull = GO.convex_hull(GO.GEOS(), points)
+
+fig = Figure()
+a1, p1 = lines(fig[1, 1], go_hull; color = 1:GI.npoint(go_hull), axis = (; title = "MonotoneChainMethod()"))
+a2, p2 = lines(fig[2, 1], lg_hull; color = 1:GI.npoint(lg_hull), axis = (; title = "GEOS()"))
+cb = Colorbar(fig[1:2, 2], p1; label = "Vertex number")
+fig
"""
+ convex_hull([method], geometries)
+
+Compute the convex hull of the points in \`geometries\`.
+Returns a \`GI.Polygon\` representing the convex hull.
+
+Note that the polygon returned is wound counterclockwise
+as in the Simple Features standard by default. If you
+choose GEOS, the winding order will be inverted.
+
+!!! warning
+ This interface only computes the 2-dimensional convex hull!
+
+ For higher dimensional hulls, use the relevant package (Qhull.jl, Quickhull.jl, or similar).
+"""
+function convex_hull end
+
+"""
+ MonotoneChainMethod()
+
+This is an algorithm for the \`convex_hull\` function.
+
+Uses [\`DelaunayTriangulation.jl\`](https://github.com/JuliaGeometry/DelaunayTriangulation.jl) to compute the convex hull.
+This is a pure Julia algorithm which provides an optimal Delaunay triangulation.
+
+See also \`convex_hull\`
+"""
+struct MonotoneChainMethod end
GrahamScanMethod, etc. can be implemented in GO as well, if someone wants to. If we add an extension on Quickhull.jl, then that would be another algorithm.
`,35)]))}const u=i(p,[["render",k]]);export{c as __pageData,u as default};
diff --git a/previews/PR239/assets/source_methods_distance.md.DLCaGxsq.js b/previews/PR239/assets/source_methods_distance.md.DLCaGxsq.js
new file mode 100644
index 000000000..f6d5521c7
--- /dev/null
+++ b/previews/PR239/assets/source_methods_distance.md.DLCaGxsq.js
@@ -0,0 +1,181 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/tlayvwm.DiwGEg2f.png",k="/GeometryOps.jl/previews/PR239/assets/cphyzje.DuBHk1fh.png",F=JSON.parse('{"title":"Distance and signed distance","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/distance.md","filePath":"source/methods/distance.md","lastUpdated":null}'),p={name:"source/methods/distance.md"};function l(e,s,d,E,r,g){return h(),a("div",null,s[0]||(s[0]=[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 positive 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)]))}const o=i(p,[["render",l]]);export{F as __pageData,o as default};
diff --git a/previews/PR239/assets/source_methods_distance.md.DLCaGxsq.lean.js b/previews/PR239/assets/source_methods_distance.md.DLCaGxsq.lean.js
new file mode 100644
index 000000000..f6d5521c7
--- /dev/null
+++ b/previews/PR239/assets/source_methods_distance.md.DLCaGxsq.lean.js
@@ -0,0 +1,181 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/tlayvwm.DiwGEg2f.png",k="/GeometryOps.jl/previews/PR239/assets/cphyzje.DuBHk1fh.png",F=JSON.parse('{"title":"Distance and signed distance","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/distance.md","filePath":"source/methods/distance.md","lastUpdated":null}'),p={name:"source/methods/distance.md"};function l(e,s,d,E,r,g){return h(),a("div",null,s[0]||(s[0]=[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 positive 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)]))}const o=i(p,[["render",l]]);export{F as __pageData,o as default};
diff --git a/previews/PR239/assets/source_methods_equals.md.BsnJrmWL.js b/previews/PR239/assets/source_methods_equals.md.BsnJrmWL.js
new file mode 100644
index 000000000..23fd097d8
--- /dev/null
+++ b/previews/PR239/assets/source_methods_equals.md.BsnJrmWL.js
@@ -0,0 +1,265 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/hvyhqaw.CgiryX2p.png",F=JSON.parse('{"title":"Equals","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/equals.md","filePath":"source/methods/equals.md","lastUpdated":null}'),h={name:"source/methods/equals.md"};function p(k,s,e,r,d,g){return l(),a("div",null,s[0]||(s[0]=[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 common 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 explicitly 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 definition.
+"""
+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 definition, 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 definition, 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)]))}const o=i(h,[["render",p]]);export{F as __pageData,o as default};
diff --git a/previews/PR239/assets/source_methods_equals.md.BsnJrmWL.lean.js b/previews/PR239/assets/source_methods_equals.md.BsnJrmWL.lean.js
new file mode 100644
index 000000000..23fd097d8
--- /dev/null
+++ b/previews/PR239/assets/source_methods_equals.md.BsnJrmWL.lean.js
@@ -0,0 +1,265 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/hvyhqaw.CgiryX2p.png",F=JSON.parse('{"title":"Equals","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/equals.md","filePath":"source/methods/equals.md","lastUpdated":null}'),h={name:"source/methods/equals.md"};function p(k,s,e,r,d,g){return l(),a("div",null,s[0]||(s[0]=[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 common 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 explicitly 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 definition.
+"""
+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 definition, 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 definition, 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)]))}const o=i(h,[["render",p]]);export{F as __pageData,o as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_contains.md.CTaz5DgK.js b/previews/PR239/assets/source_methods_geom_relations_contains.md.CTaz5DgK.js
new file mode 100644
index 000000000..098b4f9b5
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_contains.md.CTaz5DgK.js
@@ -0,0 +1,33 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const e="/GeometryOps.jl/previews/PR239/assets/rzkakxn._0R9BbFk.png",E=JSON.parse('{"title":"Contains","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/contains.md","filePath":"source/methods/geom_relations/contains.md","lastUpdated":null}'),h={name:"source/methods/geom_relations/contains.md"};function l(p,s,k,r,o,d){return t(),a("div",null,s[0]||(s[0]=[n(`
The contains function checks if a given geometry completely contains another geometry, or in other words, that the second geometry is completely 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)]))}const c=i(h,[["render",l]]);export{E as __pageData,c as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_contains.md.CTaz5DgK.lean.js b/previews/PR239/assets/source_methods_geom_relations_contains.md.CTaz5DgK.lean.js
new file mode 100644
index 000000000..098b4f9b5
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_contains.md.CTaz5DgK.lean.js
@@ -0,0 +1,33 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const e="/GeometryOps.jl/previews/PR239/assets/rzkakxn._0R9BbFk.png",E=JSON.parse('{"title":"Contains","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/contains.md","filePath":"source/methods/geom_relations/contains.md","lastUpdated":null}'),h={name:"source/methods/geom_relations/contains.md"};function l(p,s,k,r,o,d){return t(),a("div",null,s[0]||(s[0]=[n(`
The contains function checks if a given geometry completely contains another geometry, or in other words, that the second geometry is completely 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)]))}const c=i(h,[["render",l]]);export{E as __pageData,c as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_coveredby.md.BNo4Y8zx.js b/previews/PR239/assets/source_methods_geom_relations_coveredby.md.BNo4Y8zx.js
new file mode 100644
index 000000000..b0e7611c0
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_coveredby.md.BNo4Y8zx.js
@@ -0,0 +1,183 @@
+import{_ as i,c as a,a5 as n,o as e}from"./chunks/framework.onQNwZ2I.js";const l="/GeometryOps.jl/previews/PR239/assets/kbzwnsa.DC3TvBOO.png",o=JSON.parse('{"title":"CoveredBy","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/coveredby.md","filePath":"source/methods/geom_relations/coveredby.md","lastUpdated":null}'),h={name:"source/methods/geom_relations/coveredby.md"};function t(p,s,k,r,E,d){return e(),a("div",null,s[0]||(s[0]=[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, including 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, including 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)]))}const y=i(h,[["render",t]]);export{o as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_coveredby.md.BNo4Y8zx.lean.js b/previews/PR239/assets/source_methods_geom_relations_coveredby.md.BNo4Y8zx.lean.js
new file mode 100644
index 000000000..b0e7611c0
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_coveredby.md.BNo4Y8zx.lean.js
@@ -0,0 +1,183 @@
+import{_ as i,c as a,a5 as n,o as e}from"./chunks/framework.onQNwZ2I.js";const l="/GeometryOps.jl/previews/PR239/assets/kbzwnsa.DC3TvBOO.png",o=JSON.parse('{"title":"CoveredBy","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/coveredby.md","filePath":"source/methods/geom_relations/coveredby.md","lastUpdated":null}'),h={name:"source/methods/geom_relations/coveredby.md"};function t(p,s,k,r,E,d){return e(),a("div",null,s[0]||(s[0]=[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, including 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, including 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)]))}const y=i(h,[["render",t]]);export{o as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_covers.md.Ds8aZwNW.js b/previews/PR239/assets/source_methods_geom_relations_covers.md.Ds8aZwNW.js
new file mode 100644
index 000000000..9fdf77d59
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_covers.md.Ds8aZwNW.js
@@ -0,0 +1,33 @@
+import{_ as i,c as a,a5 as e,o as n}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/kbzwnsa.DC3TvBOO.png",g=JSON.parse('{"title":"Covers","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/covers.md","filePath":"source/methods/geom_relations/covers.md","lastUpdated":null}'),p={name:"source/methods/geom_relations/covers.md"};function l(h,s,k,r,o,d){return n(),a("div",null,s[0]||(s[0]=[e(`
The covers function checks if a given geometry completely 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)]))}const E=i(p,[["render",l]]);export{g as __pageData,E as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_covers.md.Ds8aZwNW.lean.js b/previews/PR239/assets/source_methods_geom_relations_covers.md.Ds8aZwNW.lean.js
new file mode 100644
index 000000000..9fdf77d59
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_covers.md.Ds8aZwNW.lean.js
@@ -0,0 +1,33 @@
+import{_ as i,c as a,a5 as e,o as n}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/kbzwnsa.DC3TvBOO.png",g=JSON.parse('{"title":"Covers","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/covers.md","filePath":"source/methods/geom_relations/covers.md","lastUpdated":null}'),p={name:"source/methods/geom_relations/covers.md"};function l(h,s,k,r,o,d){return n(),a("div",null,s[0]||(s[0]=[e(`
The covers function checks if a given geometry completely 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)]))}const E=i(p,[["render",l]]);export{g as __pageData,E as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_crosses.md.-nyWl6CC.js b/previews/PR239/assets/source_methods_geom_relations_crosses.md.-nyWl6CC.js
new file mode 100644
index 000000000..41b060fb1
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_crosses.md.-nyWl6CC.js
@@ -0,0 +1,120 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const d=JSON.parse('{"title":"Crossing checks","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/crosses.md","filePath":"source/methods/geom_relations/crosses.md","lastUpdated":null}'),p={name:"source/methods/geom_relations/crosses.md"};function h(t,s,k,e,r,E){return l(),a("div",null,s[0]||(s[0]=[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)]))}const F=i(p,[["render",h]]);export{d as __pageData,F as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_crosses.md.-nyWl6CC.lean.js b/previews/PR239/assets/source_methods_geom_relations_crosses.md.-nyWl6CC.lean.js
new file mode 100644
index 000000000..41b060fb1
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_crosses.md.-nyWl6CC.lean.js
@@ -0,0 +1,120 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const d=JSON.parse('{"title":"Crossing checks","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/crosses.md","filePath":"source/methods/geom_relations/crosses.md","lastUpdated":null}'),p={name:"source/methods/geom_relations/crosses.md"};function h(t,s,k,e,r,E){return l(),a("div",null,s[0]||(s[0]=[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)]))}const F=i(p,[["render",h]]);export{d as __pageData,F as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_disjoint.md.DH85oHhz.js b/previews/PR239/assets/source_methods_geom_relations_disjoint.md.DH85oHhz.js
new file mode 100644
index 000000000..0986ed48d
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_disjoint.md.DH85oHhz.js
@@ -0,0 +1,178 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const h="/GeometryOps.jl/previews/PR239/assets/jsdldah.C3SxJ3x-.png",o=JSON.parse('{"title":"Disjoint","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/disjoint.md","filePath":"source/methods/geom_relations/disjoint.md","lastUpdated":null}'),l={name:"source/methods/geom_relations/disjoint.md"};function p(k,s,e,r,E,g){return t(),a("div",null,s[0]||(s[0]=[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 geometry'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)]))}const y=i(l,[["render",p]]);export{o as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_disjoint.md.DH85oHhz.lean.js b/previews/PR239/assets/source_methods_geom_relations_disjoint.md.DH85oHhz.lean.js
new file mode 100644
index 000000000..0986ed48d
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_disjoint.md.DH85oHhz.lean.js
@@ -0,0 +1,178 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const h="/GeometryOps.jl/previews/PR239/assets/jsdldah.C3SxJ3x-.png",o=JSON.parse('{"title":"Disjoint","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/disjoint.md","filePath":"source/methods/geom_relations/disjoint.md","lastUpdated":null}'),l={name:"source/methods/geom_relations/disjoint.md"};function p(k,s,e,r,E,g){return t(),a("div",null,s[0]||(s[0]=[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 geometry'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)]))}const y=i(l,[["render",p]]);export{o as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_geom_geom_processors.md.CmpKdMyB.js b/previews/PR239/assets/source_methods_geom_relations_geom_geom_processors.md.CmpKdMyB.js
new file mode 100644
index 000000000..869aea8c8
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_geom_geom_processors.md.CmpKdMyB.js
@@ -0,0 +1,437 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const g=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}'),l={name:"source/methods/geom_relations/geom_geom_processors.md"};function t(p,s,k,e,r,E){return h(),a("div",null,s[0]||(s[0]=[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 boundary 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 requirements, 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 completely 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 requirements, 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 boundary 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 requirements, 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 separates 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 boundaries. 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)]))}const y=i(l,[["render",t]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_geom_geom_processors.md.CmpKdMyB.lean.js b/previews/PR239/assets/source_methods_geom_relations_geom_geom_processors.md.CmpKdMyB.lean.js
new file mode 100644
index 000000000..869aea8c8
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_geom_geom_processors.md.CmpKdMyB.lean.js
@@ -0,0 +1,437 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const g=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}'),l={name:"source/methods/geom_relations/geom_geom_processors.md"};function t(p,s,k,e,r,E){return h(),a("div",null,s[0]||(s[0]=[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 boundary 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 requirements, 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 completely 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 requirements, 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 boundary 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 requirements, 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 separates 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 boundaries. 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)]))}const y=i(l,[["render",t]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_intersects.md.Z6dLYNxj.js b/previews/PR239/assets/source_methods_geom_relations_intersects.md.Z6dLYNxj.js
new file mode 100644
index 000000000..d2d54239e
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_intersects.md.Z6dLYNxj.js
@@ -0,0 +1,27 @@
+import{_ as i,c as a,a5 as e,o as n}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/sqwzzcg.DeeQUply.png",g=JSON.parse('{"title":"Intersection checks","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/intersects.md","filePath":"source/methods/geom_relations/intersects.md","lastUpdated":null}'),p={name:"source/methods/geom_relations/intersects.md"};function l(h,s,k,r,o,d){return n(),a("div",null,s[0]||(s[0]=[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)]))}const E=i(p,[["render",l]]);export{g as __pageData,E as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_intersects.md.Z6dLYNxj.lean.js b/previews/PR239/assets/source_methods_geom_relations_intersects.md.Z6dLYNxj.lean.js
new file mode 100644
index 000000000..d2d54239e
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_intersects.md.Z6dLYNxj.lean.js
@@ -0,0 +1,27 @@
+import{_ as i,c as a,a5 as e,o as n}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/sqwzzcg.DeeQUply.png",g=JSON.parse('{"title":"Intersection checks","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/intersects.md","filePath":"source/methods/geom_relations/intersects.md","lastUpdated":null}'),p={name:"source/methods/geom_relations/intersects.md"};function l(h,s,k,r,o,d){return n(),a("div",null,s[0]||(s[0]=[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)]))}const E=i(p,[["render",l]]);export{g as __pageData,E as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_overlaps.md.BjDDEk4_.js b/previews/PR239/assets/source_methods_geom_relations_overlaps.md.BjDDEk4_.js
new file mode 100644
index 000000000..186cb7e1e
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_overlaps.md.BjDDEk4_.js
@@ -0,0 +1,212 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const p="/GeometryOps.jl/previews/PR239/assets/hvyhqaw.CgiryX2p.png",o=JSON.parse('{"title":"Overlaps","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/overlaps.md","filePath":"source/methods/geom_relations/overlaps.md","lastUpdated":null}'),t={name:"source/methods/geom_relations/overlaps.md"};function e(h,s,k,r,d,g){return l(),a("div",null,s[0]||(s[0]=[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 collinear.
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 automatically 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 respectively, 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 collinear 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 collinear 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)]))}const E=i(t,[["render",e]]);export{o as __pageData,E as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_overlaps.md.BjDDEk4_.lean.js b/previews/PR239/assets/source_methods_geom_relations_overlaps.md.BjDDEk4_.lean.js
new file mode 100644
index 000000000..186cb7e1e
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_overlaps.md.BjDDEk4_.lean.js
@@ -0,0 +1,212 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const p="/GeometryOps.jl/previews/PR239/assets/hvyhqaw.CgiryX2p.png",o=JSON.parse('{"title":"Overlaps","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/overlaps.md","filePath":"source/methods/geom_relations/overlaps.md","lastUpdated":null}'),t={name:"source/methods/geom_relations/overlaps.md"};function e(h,s,k,r,d,g){return l(),a("div",null,s[0]||(s[0]=[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 collinear.
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 automatically 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 respectively, 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 collinear 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 collinear 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)]))}const E=i(t,[["render",e]]);export{o as __pageData,E as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_touches.md.C3wGt7mS.js b/previews/PR239/assets/source_methods_geom_relations_touches.md.C3wGt7mS.js
new file mode 100644
index 000000000..99d0ad298
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_touches.md.C3wGt7mS.js
@@ -0,0 +1,174 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const h="/GeometryOps.jl/previews/PR239/assets/eytjybr.BEFUMtlf.png",o=JSON.parse('{"title":"Touches","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/touches.md","filePath":"source/methods/geom_relations/touches.md","lastUpdated":null}'),l={name:"source/methods/geom_relations/touches.md"};function e(p,s,k,r,E,g){return t(),a("div",null,s[0]||(s[0]=[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 geometry's 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 geometry's 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 boundary point interacts with
+the boundary 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 boundary 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 boundary 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 boundary points interacts
+with the polygon's boundary 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)]))}const y=i(l,[["render",e]]);export{o as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_touches.md.C3wGt7mS.lean.js b/previews/PR239/assets/source_methods_geom_relations_touches.md.C3wGt7mS.lean.js
new file mode 100644
index 000000000..99d0ad298
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_touches.md.C3wGt7mS.lean.js
@@ -0,0 +1,174 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const h="/GeometryOps.jl/previews/PR239/assets/eytjybr.BEFUMtlf.png",o=JSON.parse('{"title":"Touches","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/touches.md","filePath":"source/methods/geom_relations/touches.md","lastUpdated":null}'),l={name:"source/methods/geom_relations/touches.md"};function e(p,s,k,r,E,g){return t(),a("div",null,s[0]||(s[0]=[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 geometry's 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 geometry's 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 boundary point interacts with
+the boundary 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 boundary 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 boundary 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 boundary points interacts
+with the polygon's boundary 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)]))}const y=i(l,[["render",e]]);export{o as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_within.md.UHYdg8yN.js b/previews/PR239/assets/source_methods_geom_relations_within.md.UHYdg8yN.js
new file mode 100644
index 000000000..d8cf62dc9
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_within.md.UHYdg8yN.js
@@ -0,0 +1,193 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/rzkakxn._0R9BbFk.png",o=JSON.parse('{"title":"Within","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/within.md","filePath":"source/methods/geom_relations/within.md","lastUpdated":null}'),l={name:"source/methods/geom_relations/within.md"};function e(p,s,k,r,E,g){return h(),a("div",null,s[0]||(s[0]=[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)]))}const y=i(l,[["render",e]]);export{o as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_geom_relations_within.md.UHYdg8yN.lean.js b/previews/PR239/assets/source_methods_geom_relations_within.md.UHYdg8yN.lean.js
new file mode 100644
index 000000000..d8cf62dc9
--- /dev/null
+++ b/previews/PR239/assets/source_methods_geom_relations_within.md.UHYdg8yN.lean.js
@@ -0,0 +1,193 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/rzkakxn._0R9BbFk.png",o=JSON.parse('{"title":"Within","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/geom_relations/within.md","filePath":"source/methods/geom_relations/within.md","lastUpdated":null}'),l={name:"source/methods/geom_relations/within.md"};function e(p,s,k,r,E,g){return h(),a("div",null,s[0]||(s[0]=[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)]))}const y=i(l,[["render",e]]);export{o as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_orientation.md.Cx8oaEg5.js b/previews/PR239/assets/source_methods_orientation.md.Cx8oaEg5.js
new file mode 100644
index 000000000..da812c3ed
--- /dev/null
+++ b/previews/PR239/assets/source_methods_orientation.md.Cx8oaEg5.js
@@ -0,0 +1,100 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const E=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"};function h(t,s,e,k,r,d){return l(),a("div",null,s[0]||(s[0]=[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\` if the line goes clockwise, or \`false\` if the line goes
+counter-clockwise. "Going clockwise" means, mathematically,
+
+\`\`\`math
+\\\\left(\\\\sum_{i=2}^n (x_i - x_{i-1}) \\\\cdot (y_i + y_{i-1})\\\\right) > 0
+\`\`\`
+
+# Example
+
+\`\`\`julia
+julia> import GeoInterface as GI, GeometryOps as GO
+julia> ring = GI.LinearRing([(0, 0), (1, 1), (1, 0), (0, 0)]);
+julia> 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)]))}const o=i(p,[["render",h]]);export{E as __pageData,o as default};
diff --git a/previews/PR239/assets/source_methods_orientation.md.Cx8oaEg5.lean.js b/previews/PR239/assets/source_methods_orientation.md.Cx8oaEg5.lean.js
new file mode 100644
index 000000000..da812c3ed
--- /dev/null
+++ b/previews/PR239/assets/source_methods_orientation.md.Cx8oaEg5.lean.js
@@ -0,0 +1,100 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const E=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"};function h(t,s,e,k,r,d){return l(),a("div",null,s[0]||(s[0]=[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\` if the line goes clockwise, or \`false\` if the line goes
+counter-clockwise. "Going clockwise" means, mathematically,
+
+\`\`\`math
+\\\\left(\\\\sum_{i=2}^n (x_i - x_{i-1}) \\\\cdot (y_i + y_{i-1})\\\\right) > 0
+\`\`\`
+
+# Example
+
+\`\`\`julia
+julia> import GeoInterface as GI, GeometryOps as GO
+julia> ring = GI.LinearRing([(0, 0), (1, 1), (1, 0), (0, 0)]);
+julia> 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)]))}const o=i(p,[["render",h]]);export{E as __pageData,o as default};
diff --git a/previews/PR239/assets/source_methods_polygonize.md.CCOlggGo.js b/previews/PR239/assets/source_methods_polygonize.md.CCOlggGo.js
new file mode 100644
index 000000000..19c0c3b97
--- /dev/null
+++ b/previews/PR239/assets/source_methods_polygonize.md.CCOlggGo.js
@@ -0,0 +1,289 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Polygonizing raster data","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/polygonize.md","filePath":"source/methods/polygonize.md","lastUpdated":null}'),l={name:"source/methods/polygonize.md"};function p(t,s,k,e,d,E){return h(),a("div",null,s[0]||(s[0]=[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 polygons 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 empty 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)]))}const y=i(l,[["render",p]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_methods_polygonize.md.CCOlggGo.lean.js b/previews/PR239/assets/source_methods_polygonize.md.CCOlggGo.lean.js
new file mode 100644
index 000000000..19c0c3b97
--- /dev/null
+++ b/previews/PR239/assets/source_methods_polygonize.md.CCOlggGo.lean.js
@@ -0,0 +1,289 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Polygonizing raster data","description":"","frontmatter":{},"headers":[],"relativePath":"source/methods/polygonize.md","filePath":"source/methods/polygonize.md","lastUpdated":null}'),l={name:"source/methods/polygonize.md"};function p(t,s,k,e,d,E){return h(),a("div",null,s[0]||(s[0]=[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 polygons 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 empty 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)]))}const y=i(l,[["render",p]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_not_implemented_yet.md.BRH4xbkQ.js b/previews/PR239/assets/source_not_implemented_yet.md.BRH4xbkQ.js
new file mode 100644
index 000000000..9f702e26d
--- /dev/null
+++ b/previews/PR239/assets/source_not_implemented_yet.md.BRH4xbkQ.js
@@ -0,0 +1,4 @@
+import{_ as i,c as t,a5 as s,o as a}from"./chunks/framework.onQNwZ2I.js";const k=JSON.parse('{"title":"Not implemented yet","description":"","frontmatter":{},"headers":[],"relativePath":"source/not_implemented_yet.md","filePath":"source/not_implemented_yet.md","lastUpdated":null}'),n={name:"source/not_implemented_yet.md"};function l(p,e,h,o,r,d){return a(),t("div",null,e[0]||(e[0]=[s(`
All of the functions in this file are not implemented in Julia yet. Some of them may have implementations in LibGEOS which we can use via an extension, but there is no native-Julia implementation for them.
julia
function symdifference end
+function buffer end
+function convexhull end
+function concavehull end
`,5)]))}const c=i(n,[["render",l]]);export{k as __pageData,c as default};
diff --git a/previews/PR239/assets/source_not_implemented_yet.md.BRH4xbkQ.lean.js b/previews/PR239/assets/source_not_implemented_yet.md.BRH4xbkQ.lean.js
new file mode 100644
index 000000000..9f702e26d
--- /dev/null
+++ b/previews/PR239/assets/source_not_implemented_yet.md.BRH4xbkQ.lean.js
@@ -0,0 +1,4 @@
+import{_ as i,c as t,a5 as s,o as a}from"./chunks/framework.onQNwZ2I.js";const k=JSON.parse('{"title":"Not implemented yet","description":"","frontmatter":{},"headers":[],"relativePath":"source/not_implemented_yet.md","filePath":"source/not_implemented_yet.md","lastUpdated":null}'),n={name:"source/not_implemented_yet.md"};function l(p,e,h,o,r,d){return a(),t("div",null,e[0]||(e[0]=[s(`
All of the functions in this file are not implemented in Julia yet. Some of them may have implementations in LibGEOS which we can use via an extension, but there is no native-Julia implementation for them.
julia
function symdifference end
+function buffer end
+function convexhull end
+function concavehull end
`,5)]))}const c=i(n,[["render",l]]);export{k as __pageData,c as default};
diff --git a/previews/PR239/assets/source_primitives.md.Dyw7zzpW.js b/previews/PR239/assets/source_primitives.md.Dyw7zzpW.js
new file mode 100644
index 000000000..acef8bd21
--- /dev/null
+++ b/previews/PR239/assets/source_primitives.md.Dyw7zzpW.js
@@ -0,0 +1 @@
+import{_ as a,c as s,j as e,a as r,o as i}from"./chunks/framework.onQNwZ2I.js";const f=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/primitives.md","filePath":"source/primitives.md","lastUpdated":null}'),n={name:"source/primitives.md"};function l(o,t,p,c,d,m){return i(),s("div",null,t[0]||(t[0]=[e("hr",null,null,-1),e("p",null,[e("em",null,[r("This page was generated using "),e("a",{href:"https://github.com/fredrikekre/Literate.jl",target:"_blank",rel:"noreferrer"},"Literate.jl"),r(".")])],-1)]))}const _=a(n,[["render",l]]);export{f as __pageData,_ as default};
diff --git a/previews/PR239/assets/source_primitives.md.Dyw7zzpW.lean.js b/previews/PR239/assets/source_primitives.md.Dyw7zzpW.lean.js
new file mode 100644
index 000000000..acef8bd21
--- /dev/null
+++ b/previews/PR239/assets/source_primitives.md.Dyw7zzpW.lean.js
@@ -0,0 +1 @@
+import{_ as a,c as s,j as e,a as r,o as i}from"./chunks/framework.onQNwZ2I.js";const f=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/primitives.md","filePath":"source/primitives.md","lastUpdated":null}'),n={name:"source/primitives.md"};function l(o,t,p,c,d,m){return i(),s("div",null,t[0]||(t[0]=[e("hr",null,null,-1),e("p",null,[e("em",null,[r("This page was generated using "),e("a",{href:"https://github.com/fredrikekre/Literate.jl",target:"_blank",rel:"noreferrer"},"Literate.jl"),r(".")])],-1)]))}const _=a(n,[["render",l]]);export{f as __pageData,_ as default};
diff --git a/previews/PR239/assets/source_src_GeometryOpsCore.md.BF7KPh3I.js b/previews/PR239/assets/source_src_GeometryOpsCore.md.BF7KPh3I.js
new file mode 100644
index 000000000..95056e814
--- /dev/null
+++ b/previews/PR239/assets/source_src_GeometryOpsCore.md.BF7KPh3I.js
@@ -0,0 +1,25 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/GeometryOpsCore.md","filePath":"source/src/GeometryOpsCore.md","lastUpdated":null}'),l={name:"source/src/GeometryOpsCore.md"};function e(p,s,h,k,r,E){return t(),a("div",null,s[0]||(s[0]=[n(`
julia
module GeometryOpsCore
+
+using Base.Threads: nthreads, @threads, @spawn
+
+import GeoInterface
+import GeoInterface as GI
+import GeoInterface: Extents
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
+
+using Tables
+using DataAPI
+
+include("keyword_docs.jl")
+include("types.jl")
+
+include("apply.jl")
+include("applyreduce.jl")
+include("other_primitives.jl")
+include("geometry_utils.jl")
+
+end
`,5)]))}const y=i(l,[["render",e]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_src_GeometryOpsCore.md.BF7KPh3I.lean.js b/previews/PR239/assets/source_src_GeometryOpsCore.md.BF7KPh3I.lean.js
new file mode 100644
index 000000000..95056e814
--- /dev/null
+++ b/previews/PR239/assets/source_src_GeometryOpsCore.md.BF7KPh3I.lean.js
@@ -0,0 +1,25 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/GeometryOpsCore.md","filePath":"source/src/GeometryOpsCore.md","lastUpdated":null}'),l={name:"source/src/GeometryOpsCore.md"};function e(p,s,h,k,r,E){return t(),a("div",null,s[0]||(s[0]=[n(`
julia
module GeometryOpsCore
+
+using Base.Threads: nthreads, @threads, @spawn
+
+import GeoInterface
+import GeoInterface as GI
+import GeoInterface: Extents
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
+
+using Tables
+using DataAPI
+
+include("keyword_docs.jl")
+include("types.jl")
+
+include("apply.jl")
+include("applyreduce.jl")
+include("other_primitives.jl")
+include("geometry_utils.jl")
+
+end
`,5)]))}const y=i(l,[["render",e]]);export{g as __pageData,y as default};
diff --git a/previews/PR239/assets/source_src_apply.md.C1jwRpiI.js b/previews/PR239/assets/source_src_apply.md.C1jwRpiI.js
new file mode 100644
index 000000000..683875f0f
--- /dev/null
+++ b/previews/PR239/assets/source_src_apply.md.C1jwRpiI.js
@@ -0,0 +1,144 @@
+import{_ as h,c as l,a5 as a,j as i,a as t,G as n,B as p,o as k}from"./chunks/framework.onQNwZ2I.js";const b=JSON.parse('{"title":"apply","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/apply.md","filePath":"source/src/apply.md","lastUpdated":null}'),r={name:"source/src/apply.md"},d={class:"jldocstring custom-block",open:""},g={class:"jldocstring custom-block",open:""};function o(E,s,c,y,F,u){const e=p("Badge");return k(),l("div",null,[s[6]||(s[6]=a('
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. Then, the geometry or structure is rebuilt.
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\n (GI.y(p), GI.x(p))\nend
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.
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
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.
Finally, we ensure that metadata is propagated correctly. This can only happen if the original table supports metadata reads, and the result supports metadata writes.
julia
if DataAPI.metadatasupport(typeof(result)).write
Copy over all metadata from the original table to the new table, if the original table supports metadata reading.
julia
if DataAPI.metadatasupport(IterableType).read
+ for (key, (value, style)) in DataAPI.metadata(iterable; style = true)
Default styles are not preserved on data transformation, so we must skip them!
julia
style == :default && continue
We assume that any other style is preserved.
julia
DataAPI.metadata!(result, key, value; style)
+ end
+ end
We don't usually care about the original table's metadata for GEOINTERFACE namespaced keys, so we should set the crs and geometrycolumns metadata if they are present. Ensure that GEOINTERFACE:geometrycolumns and GEOINTERFACE:crs are set!
julia
mdk = DataAPI.metadatakeys(result)
If the user has asked for geometry columns to persist, they would be here, so we don't need to set them.
julia
if !("GEOINTERFACE:geometrycolumns" in mdk)
If the geometry columns are not already set, we need to set them.
julia
DataAPI.metadata!(result, "GEOINTERFACE:geometrycolumns", (geometry_column,); style = :default)
+ end
Force reset CRS always, since you can pass crs to apply.
julia
new_crs = if haskey(kw, :crs)
+ kw[:crs]
+ else
+ GI.crs(iterable) # this will automatically check \`GEOINTERFACE:crs\` unless the type has a specialized implementation.
+ end
+
+ DataAPI.metadata!(result, "GEOINTERFACE:crs", new_crs; style = :default)
+ end
+
+ return result
+end
Rewrap all FeatureCollectionTrait feature collections as GI.FeatureCollection Maybe use threads to call _apply on component features
julia
@inline function _apply(f::F, target, ::GI.FeatureCollectionTrait, fc;
+ crs=GI.crs(fc), calc_extent=_False(), threaded
+) where F
Run _apply on all features in the feature collection, possibly threaded
julia
apply_to_feature(i) =
+ _apply(f, target, GI.getfeature(fc, i); crs, calc_extent, threaded=_False())::GI.Feature
+ features = _maptasks(apply_to_feature, 1:GI.nfeature(fc), threaded)
+ if calc_extent isa _True
Return a new geometry of 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
+
+
+### \`_maptasks\` - flexible, threaded \`map\`
+
+using Base.Threads: nthreads, @threads, @spawn
Threading utility, modified Mason Protters threading PSA run f over ntasks, where f receives an AbstractArray/range of linear indices
julia
@inline function _maptasks(f::F, taskrange, threaded::_True)::Vector where F
+ ntasks = length(taskrange)
Customize this as needed. More tasks have more overhead, but better load balancing
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
`,107))])}const m=h(r,[["render",o]]);export{b as __pageData,m as default};
diff --git a/previews/PR239/assets/source_src_apply.md.C1jwRpiI.lean.js b/previews/PR239/assets/source_src_apply.md.C1jwRpiI.lean.js
new file mode 100644
index 000000000..683875f0f
--- /dev/null
+++ b/previews/PR239/assets/source_src_apply.md.C1jwRpiI.lean.js
@@ -0,0 +1,144 @@
+import{_ as h,c as l,a5 as a,j as i,a as t,G as n,B as p,o as k}from"./chunks/framework.onQNwZ2I.js";const b=JSON.parse('{"title":"apply","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/apply.md","filePath":"source/src/apply.md","lastUpdated":null}'),r={name:"source/src/apply.md"},d={class:"jldocstring custom-block",open:""},g={class:"jldocstring custom-block",open:""};function o(E,s,c,y,F,u){const e=p("Badge");return k(),l("div",null,[s[6]||(s[6]=a('
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. Then, the geometry or structure is rebuilt.
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\n (GI.y(p), GI.x(p))\nend
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.
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
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.
Finally, we ensure that metadata is propagated correctly. This can only happen if the original table supports metadata reads, and the result supports metadata writes.
julia
if DataAPI.metadatasupport(typeof(result)).write
Copy over all metadata from the original table to the new table, if the original table supports metadata reading.
julia
if DataAPI.metadatasupport(IterableType).read
+ for (key, (value, style)) in DataAPI.metadata(iterable; style = true)
Default styles are not preserved on data transformation, so we must skip them!
julia
style == :default && continue
We assume that any other style is preserved.
julia
DataAPI.metadata!(result, key, value; style)
+ end
+ end
We don't usually care about the original table's metadata for GEOINTERFACE namespaced keys, so we should set the crs and geometrycolumns metadata if they are present. Ensure that GEOINTERFACE:geometrycolumns and GEOINTERFACE:crs are set!
julia
mdk = DataAPI.metadatakeys(result)
If the user has asked for geometry columns to persist, they would be here, so we don't need to set them.
julia
if !("GEOINTERFACE:geometrycolumns" in mdk)
If the geometry columns are not already set, we need to set them.
julia
DataAPI.metadata!(result, "GEOINTERFACE:geometrycolumns", (geometry_column,); style = :default)
+ end
Force reset CRS always, since you can pass crs to apply.
julia
new_crs = if haskey(kw, :crs)
+ kw[:crs]
+ else
+ GI.crs(iterable) # this will automatically check \`GEOINTERFACE:crs\` unless the type has a specialized implementation.
+ end
+
+ DataAPI.metadata!(result, "GEOINTERFACE:crs", new_crs; style = :default)
+ end
+
+ return result
+end
Rewrap all FeatureCollectionTrait feature collections as GI.FeatureCollection Maybe use threads to call _apply on component features
julia
@inline function _apply(f::F, target, ::GI.FeatureCollectionTrait, fc;
+ crs=GI.crs(fc), calc_extent=_False(), threaded
+) where F
Run _apply on all features in the feature collection, possibly threaded
julia
apply_to_feature(i) =
+ _apply(f, target, GI.getfeature(fc, i); crs, calc_extent, threaded=_False())::GI.Feature
+ features = _maptasks(apply_to_feature, 1:GI.nfeature(fc), threaded)
+ if calc_extent isa _True
Return a new geometry of 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
+
+
+### \`_maptasks\` - flexible, threaded \`map\`
+
+using Base.Threads: nthreads, @threads, @spawn
Threading utility, modified Mason Protters threading PSA run f over ntasks, where f receives an AbstractArray/range of linear indices
julia
@inline function _maptasks(f::F, taskrange, threaded::_True)::Vector where F
+ ntasks = length(taskrange)
Customize this as needed. More tasks have more overhead, but better load balancing
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
`,107))])}const m=h(r,[["render",o]]);export{b as __pageData,m as default};
diff --git a/previews/PR239/assets/source_src_applyreduce.md.vbUWBm8w.js b/previews/PR239/assets/source_src_applyreduce.md.vbUWBm8w.js
new file mode 100644
index 000000000..5c5d859a2
--- /dev/null
+++ b/previews/PR239/assets/source_src_applyreduce.md.vbUWBm8w.js
@@ -0,0 +1,72 @@
+import{_ as i,c as a,a5 as t,o as n}from"./chunks/framework.onQNwZ2I.js";const E=JSON.parse('{"title":"applyreduce","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/applyreduce.md","filePath":"source/src/applyreduce.md","lastUpdated":null}'),h={name:"source/src/applyreduce.md"};function e(p,s,l,k,r,d){return n(),a("div",null,s[0]||(s[0]=[t(`
This file mainly defines the applyreduce function.
This performs apply, but then reduces the result after flattening instead of rebuilding the geometry.
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.
centroid, area and distance have been implemented using the applyreduce framework.
julia
"""
+ 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
+
+### \`_mapreducetasks\` - flexible, threaded mapreduce
+
+import Base.Threads: nthreads, @threads, @spawn
Threading utility, modified Mason Protters threading PSA run f over ntasks, where f receives an AbstractArray/range of linear indices
WARNING: this will not work for mean/median - only ops where grouping is possible. That's because the implementation operates in chunks, and not globally.
If you absolutely need a single chunk, then threaded = false will always decompose to straight mapreduce without grouping.
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
`,51)]))}const y=i(h,[["render",e]]);export{E as __pageData,y as default};
diff --git a/previews/PR239/assets/source_src_applyreduce.md.vbUWBm8w.lean.js b/previews/PR239/assets/source_src_applyreduce.md.vbUWBm8w.lean.js
new file mode 100644
index 000000000..5c5d859a2
--- /dev/null
+++ b/previews/PR239/assets/source_src_applyreduce.md.vbUWBm8w.lean.js
@@ -0,0 +1,72 @@
+import{_ as i,c as a,a5 as t,o as n}from"./chunks/framework.onQNwZ2I.js";const E=JSON.parse('{"title":"applyreduce","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/applyreduce.md","filePath":"source/src/applyreduce.md","lastUpdated":null}'),h={name:"source/src/applyreduce.md"};function e(p,s,l,k,r,d){return n(),a("div",null,s[0]||(s[0]=[t(`
This file mainly defines the applyreduce function.
This performs apply, but then reduces the result after flattening instead of rebuilding the geometry.
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.
centroid, area and distance have been implemented using the applyreduce framework.
julia
"""
+ 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
+
+### \`_mapreducetasks\` - flexible, threaded mapreduce
+
+import Base.Threads: nthreads, @threads, @spawn
Threading utility, modified Mason Protters threading PSA run f over ntasks, where f receives an AbstractArray/range of linear indices
WARNING: this will not work for mean/median - only ops where grouping is possible. That's because the implementation operates in chunks, and not globally.
If you absolutely need a single chunk, then threaded = false will always decompose to straight mapreduce without grouping.
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
`,51)]))}const y=i(h,[["render",e]]);export{E as __pageData,y as default};
diff --git a/previews/PR239/assets/source_src_geometry_utils.md.CpDbCg3A.js b/previews/PR239/assets/source_src_geometry_utils.md.CpDbCg3A.js
new file mode 100644
index 000000000..ffd71c493
--- /dev/null
+++ b/previews/PR239/assets/source_src_geometry_utils.md.CpDbCg3A.js
@@ -0,0 +1,2 @@
+import{_ as i,c as a,a5 as t,o as e}from"./chunks/framework.onQNwZ2I.js";const E=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/geometry_utils.md","filePath":"source/src/geometry_utils.md","lastUpdated":null}'),n={name:"source/src/geometry_utils.md"};function h(l,s,k,p,r,g){return e(),a("div",null,s[0]||(s[0]=[t(`
`,3)]))}const o=i(n,[["render",h]]);export{E as __pageData,o as default};
diff --git a/previews/PR239/assets/source_src_geometry_utils.md.CpDbCg3A.lean.js b/previews/PR239/assets/source_src_geometry_utils.md.CpDbCg3A.lean.js
new file mode 100644
index 000000000..ffd71c493
--- /dev/null
+++ b/previews/PR239/assets/source_src_geometry_utils.md.CpDbCg3A.lean.js
@@ -0,0 +1,2 @@
+import{_ as i,c as a,a5 as t,o as e}from"./chunks/framework.onQNwZ2I.js";const E=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/geometry_utils.md","filePath":"source/src/geometry_utils.md","lastUpdated":null}'),n={name:"source/src/geometry_utils.md"};function h(l,s,k,p,r,g){return e(),a("div",null,s[0]||(s[0]=[t(`
`,3)]))}const o=i(n,[["render",h]]);export{E as __pageData,o as default};
diff --git a/previews/PR239/assets/source_src_keyword_docs.md.BxLB2oH3.js b/previews/PR239/assets/source_src_keyword_docs.md.BxLB2oH3.js
new file mode 100644
index 000000000..7b174f887
--- /dev/null
+++ b/previews/PR239/assets/source_src_keyword_docs.md.BxLB2oH3.js
@@ -0,0 +1 @@
+import{_ as a,c as i,a5 as t,o as e}from"./chunks/framework.onQNwZ2I.js";const c=JSON.parse('{"title":"Keyword docs","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/keyword_docs.md","filePath":"source/src/keyword_docs.md","lastUpdated":null}'),n={name:"source/src/keyword_docs.md"};function l(h,s,o,r,p,d){return e(),i("div",null,s[0]||(s[0]=[t('
This file defines common keyword documentation, that can be spliced into docstrings.
julia
const THREADED_KEYWORD = "- `threaded`: `true` or `false`. Whether to use multithreading. Defaults to `false`."\nconst CRS_KEYWORD = "- `crs`: The CRS to attach to geometries. Defaults to `nothing`."\nconst CALC_EXTENT_KEYWORD = "- `calc_extent`: `true` or `false`. Whether to calculate the extent. Defaults to `false`."\n\nconst APPLY_KEYWORDS = """\n$THREADED_KEYWORD\n$CRS_KEYWORD\n$CALC_EXTENT_KEYWORD\n"""
',5)]))}const u=a(n,[["render",l]]);export{c as __pageData,u as default};
diff --git a/previews/PR239/assets/source_src_keyword_docs.md.BxLB2oH3.lean.js b/previews/PR239/assets/source_src_keyword_docs.md.BxLB2oH3.lean.js
new file mode 100644
index 000000000..7b174f887
--- /dev/null
+++ b/previews/PR239/assets/source_src_keyword_docs.md.BxLB2oH3.lean.js
@@ -0,0 +1 @@
+import{_ as a,c as i,a5 as t,o as e}from"./chunks/framework.onQNwZ2I.js";const c=JSON.parse('{"title":"Keyword docs","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/keyword_docs.md","filePath":"source/src/keyword_docs.md","lastUpdated":null}'),n={name:"source/src/keyword_docs.md"};function l(h,s,o,r,p,d){return e(),i("div",null,s[0]||(s[0]=[t('
This file defines common keyword documentation, that can be spliced into docstrings.
julia
const THREADED_KEYWORD = "- `threaded`: `true` or `false`. Whether to use multithreading. Defaults to `false`."\nconst CRS_KEYWORD = "- `crs`: The CRS to attach to geometries. Defaults to `nothing`."\nconst CALC_EXTENT_KEYWORD = "- `calc_extent`: `true` or `false`. Whether to calculate the extent. Defaults to `false`."\n\nconst APPLY_KEYWORDS = """\n$THREADED_KEYWORD\n$CRS_KEYWORD\n$CALC_EXTENT_KEYWORD\n"""
',5)]))}const u=a(n,[["render",l]]);export{c as __pageData,u as default};
diff --git a/previews/PR239/assets/source_src_other_primitives.md.BVzBrNUT.js b/previews/PR239/assets/source_src_other_primitives.md.BVzBrNUT.js
new file mode 100644
index 000000000..9d232a003
--- /dev/null
+++ b/previews/PR239/assets/source_src_other_primitives.md.BVzBrNUT.js
@@ -0,0 +1,131 @@
+import{_ as k,c as l,j as i,a,G as h,a5 as t,B as p,o as e}from"./chunks/framework.onQNwZ2I.js";const A=JSON.parse('{"title":"Other primitives (unwrap, flatten, etc)","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/other_primitives.md","filePath":"source/src/other_primitives.md","lastUpdated":null}'),r={name:"source/src/other_primitives.md"},E={class:"jldocstring custom-block",open:""},d={class:"jldocstring custom-block",open:""},g={class:"jldocstring custom-block",open:""},y={class:"jldocstring custom-block",open:""};function F(o,s,c,C,u,m){const n=p("Badge");return e(),l("div",null,[s[12]||(s[12]=i("h1",{id:"Other-primitives-(unwrap,-flatten,-etc)",tabindex:"-1"},[a("Other primitives (unwrap, flatten, etc) "),i("a",{class:"header-anchor",href:"#Other-primitives-(unwrap,-flatten,-etc)","aria-label":'Permalink to "Other primitives (unwrap, flatten, etc) {#Other-primitives-(unwrap,-flatten,-etc)}"'},"")],-1)),s[13]||(s[13]=i("p",null,"This file defines the following primitives:",-1)),i("details",E,[i("summary",null,[s[0]||(s[0]=i("a",{id:"GeometryOpsCore.unwrap-source-src-other_primitives",href:"#GeometryOpsCore.unwrap-source-src-other_primitives"},[i("span",{class:"jlbinding"},"GeometryOpsCore.unwrap")],-1)),s[1]||(s[1]=a()),h(n,{type:"info",class:"jlObjectType jlFunction",text:"Function"})]),s[2]||(s[2]=t(`
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.
"""
+ 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)
Try to flatten over iterables
julia
function _flatten(f, ::Type{Target}, ::Nothing, iterable) where Target
+ if Tables.istable(iterable)
+ column = Tables.getcolumn(iterable, first(GI.geometrycolumns(iterable)))
+ Iterators.map(x -> _flatten(f, Target, x), column) |> Iterators.flatten
+ else
+ Iterators.map(x -> _flatten(f, Target, x), iterable) |> Iterators.flatten
+ end
+end
Flatten feature collections
julia
function _flatten(f, ::Type{Target}, ::GI.FeatureCollectionTrait, fc) where Target
+ Iterators.map(GI.getfeature(fc)) do feature
+ _flatten(f, Target, feature)
+ end |> Iterators.flatten
+end
+_flatten(f, ::Type{Target}, ::GI.FeatureTrait, feature) where Target =
+ _flatten(f, Target, GI.geometry(feature))
_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\`.
+
+Usually 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"))
+
+"""
+ 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)
+ haveZ = (GI.is3d(child) for child in child_geoms)
+ haveM = (GI.ismeasured(child) for child in child_geoms)
+
+ consistentZ = length(child_geoms) == 1 ? true : all(==(first(haveZ)), haveZ)
+ consistentM = length(child_geoms) == 1 ? true : all(==(first(haveM)), haveM)
+
+ if !consistentZ || !consistentM
+ @show consistentZ consistentM
+ @show GI.is3d.(child_geoms)
+ @show GI.ismeasured.(child_geoms)
+ throw(ArgumentError("child geometries do not have consistent 3d or measure attributes."))
+ end
+
+ hasZ = first(haveZ)
+ hasM = first(haveM)
+
+ return T{hasZ,hasM}(child_geoms; crs, extent)
+end
`,41))])}const B=k(r,[["render",F]]);export{A as __pageData,B as default};
diff --git a/previews/PR239/assets/source_src_other_primitives.md.BVzBrNUT.lean.js b/previews/PR239/assets/source_src_other_primitives.md.BVzBrNUT.lean.js
new file mode 100644
index 000000000..9d232a003
--- /dev/null
+++ b/previews/PR239/assets/source_src_other_primitives.md.BVzBrNUT.lean.js
@@ -0,0 +1,131 @@
+import{_ as k,c as l,j as i,a,G as h,a5 as t,B as p,o as e}from"./chunks/framework.onQNwZ2I.js";const A=JSON.parse('{"title":"Other primitives (unwrap, flatten, etc)","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/other_primitives.md","filePath":"source/src/other_primitives.md","lastUpdated":null}'),r={name:"source/src/other_primitives.md"},E={class:"jldocstring custom-block",open:""},d={class:"jldocstring custom-block",open:""},g={class:"jldocstring custom-block",open:""},y={class:"jldocstring custom-block",open:""};function F(o,s,c,C,u,m){const n=p("Badge");return e(),l("div",null,[s[12]||(s[12]=i("h1",{id:"Other-primitives-(unwrap,-flatten,-etc)",tabindex:"-1"},[a("Other primitives (unwrap, flatten, etc) "),i("a",{class:"header-anchor",href:"#Other-primitives-(unwrap,-flatten,-etc)","aria-label":'Permalink to "Other primitives (unwrap, flatten, etc) {#Other-primitives-(unwrap,-flatten,-etc)}"'},"")],-1)),s[13]||(s[13]=i("p",null,"This file defines the following primitives:",-1)),i("details",E,[i("summary",null,[s[0]||(s[0]=i("a",{id:"GeometryOpsCore.unwrap-source-src-other_primitives",href:"#GeometryOpsCore.unwrap-source-src-other_primitives"},[i("span",{class:"jlbinding"},"GeometryOpsCore.unwrap")],-1)),s[1]||(s[1]=a()),h(n,{type:"info",class:"jlObjectType jlFunction",text:"Function"})]),s[2]||(s[2]=t(`
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.
"""
+ 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)
Try to flatten over iterables
julia
function _flatten(f, ::Type{Target}, ::Nothing, iterable) where Target
+ if Tables.istable(iterable)
+ column = Tables.getcolumn(iterable, first(GI.geometrycolumns(iterable)))
+ Iterators.map(x -> _flatten(f, Target, x), column) |> Iterators.flatten
+ else
+ Iterators.map(x -> _flatten(f, Target, x), iterable) |> Iterators.flatten
+ end
+end
Flatten feature collections
julia
function _flatten(f, ::Type{Target}, ::GI.FeatureCollectionTrait, fc) where Target
+ Iterators.map(GI.getfeature(fc)) do feature
+ _flatten(f, Target, feature)
+ end |> Iterators.flatten
+end
+_flatten(f, ::Type{Target}, ::GI.FeatureTrait, feature) where Target =
+ _flatten(f, Target, GI.geometry(feature))
_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\`.
+
+Usually 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"))
+
+"""
+ 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)
+ haveZ = (GI.is3d(child) for child in child_geoms)
+ haveM = (GI.ismeasured(child) for child in child_geoms)
+
+ consistentZ = length(child_geoms) == 1 ? true : all(==(first(haveZ)), haveZ)
+ consistentM = length(child_geoms) == 1 ? true : all(==(first(haveM)), haveM)
+
+ if !consistentZ || !consistentM
+ @show consistentZ consistentM
+ @show GI.is3d.(child_geoms)
+ @show GI.ismeasured.(child_geoms)
+ throw(ArgumentError("child geometries do not have consistent 3d or measure attributes."))
+ end
+
+ hasZ = first(haveZ)
+ hasM = first(haveM)
+
+ return T{hasZ,hasM}(child_geoms; crs, extent)
+end
`,41))])}const B=k(r,[["render",F]]);export{A as __pageData,B as default};
diff --git a/previews/PR239/assets/source_src_types.md.BulrghgC.js b/previews/PR239/assets/source_src_types.md.BulrghgC.js
new file mode 100644
index 000000000..21ac874a0
--- /dev/null
+++ b/previews/PR239/assets/source_src_types.md.BulrghgC.js
@@ -0,0 +1,111 @@
+import{_ as a,c as i,a5 as n,o as e}from"./chunks/framework.onQNwZ2I.js";const c=JSON.parse('{"title":"Types","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/types.md","filePath":"source/src/types.md","lastUpdated":null}'),t={name:"source/src/types.md"};function l(p,s,h,k,r,o){return e(),i("div",null,s[0]||(s[0]=[n(`
A manifold is mathematically defined as a topological space that resembles Euclidean space locally.
In GeometryOps (and geodesy more generally), there are three manifolds we care about:
Planar: the 2d plane, a completely Euclidean manifold
Spherical: the unit sphere, but one where areas are multiplied by the radius of the Earth. This is not Euclidean globally, but all map projections attempt to represent the sphere on the Euclidean 2D plane to varying degrees of success.
Geodesic: the ellipsoid, the closest we can come to representing the Earth by a simple geometric shape. Parametrized by semimajor_axis and inv_flattening.
Generally, we aim to have Linear and Spherical be operable everywhere, whereas Geodesic will only apply in specific circumstances. Currently, those circumstances are area and segmentize, but this could be extended with time and https://github.com/JuliaGeo/SphericalGeodesics.jl.
julia
export Planar, Spherical, Geodesic
+export TraitTarget
+export BoolsAsTypes, _True, _False, _booltype
+
+"""
+ abstract type Manifold
+
+A manifold is mathematically defined as a topological space that resembles Euclidean space locally.
+
+We use the manifold definition to define the space in which an operation should be performed, or where a geometry lies.
+
+Currently we have \`Planar\`, \`Spherical\`, and \`Geodesic\` manifolds.
+"""
+abstract type Manifold end
+
+"""
+ Planar()
+
+A planar manifold refers to the 2D Euclidean plane.
+
+Z coordinates may be accepted but will not influence geometry calculations, which
+are done purely on 2D geometry. This is the standard "2.5D" model used by e.g. GEOS.
+"""
+struct Planar <: Manifold
+end
+
+"""
+ Spherical(; radius)
+
+A spherical manifold means that the geometry is on the 3-sphere (but is represented by 2-D longitude and latitude).
+
+By default, the radius is defined as the mean radius of the Earth, \`6371008.8 m\`.
+
+# Extended help
+
+!!! note
+ The traditional definition of spherical coordinates in physics and mathematics,
+ \`\`r, \\\\theta, \\\\phi\`\`, uses the _colatitude_, that measures angular displacement from the \`z\`-axis.
+
+ Here, we use the geographic definition of longitude and latitude, meaning
+ that \`lon\` is longitude between -180 and 180, and \`lat\` is latitude between
+ \`-90\` (south pole) and \`90\` (north pole).
+"""
+Base.@kwdef struct Spherical{T} <: Manifold
+ radius::T = 6371008.8
+end
+
+"""
+ Geodesic(; semimajor_axis, inv_flattening)
+
+A geodesic manifold means that the geometry is on a 3-dimensional ellipsoid, parameterized by \`semimajor_axis\` (\`\`a\`\` in mathematical parlance)
+and \`inv_flattening\` (\`\`1/f\`\`).
+
+Usually, this is only relevant for area and segmentization calculations. It becomes more relevant as one grows closer to the poles (or equator).
+"""
+Base.@kwdef struct Geodesic{T} <: Manifold
+ semimajor_axis::T = 6378137.0
+ inv_flattening::T = 298.257223563
+end
This struct holds a trait parameter or a union of trait parameters. It's essentially a way to construct unions.
julia
"""
+ 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)...}}()
+
+
+Base.in(::Trait, ::TraitTarget{Target}) where {Trait <: GI.AbstractTrait, Target} = Trait <: Target
In apply and applyreduce, 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.
TODO: should we switch to Static.jl?
julia
"""
+ abstract type BoolsAsTypes
+
+"""
+abstract type BoolsAsTypes end
+
+"""
+ struct _True <: BoolsAsTypes
+
+A struct that means \`true\`.
+"""
+struct _True <: BoolsAsTypes end
+
+"""
+ struct _False <: BoolsAsTypes
+
+A struct that means \`false\`.
+"""
+struct _False <: BoolsAsTypes end
+
+"""
+ _booltype(x)
+
+Returns a \`BoolsAsTypes\` from \`x\`, whether it's a boolean or a BoolsAsTypes.
+"""
+function _booltype end
+
+@inline _booltype(x::Bool)::BoolsAsTypes = x ? _True() : _False()
+@inline _booltype(x::BoolsAsTypes)::BoolsAsTypes = x
`,24)]))}const F=a(t,[["render",l]]);export{c as __pageData,F as default};
diff --git a/previews/PR239/assets/source_src_types.md.BulrghgC.lean.js b/previews/PR239/assets/source_src_types.md.BulrghgC.lean.js
new file mode 100644
index 000000000..21ac874a0
--- /dev/null
+++ b/previews/PR239/assets/source_src_types.md.BulrghgC.lean.js
@@ -0,0 +1,111 @@
+import{_ as a,c as i,a5 as n,o as e}from"./chunks/framework.onQNwZ2I.js";const c=JSON.parse('{"title":"Types","description":"","frontmatter":{},"headers":[],"relativePath":"source/src/types.md","filePath":"source/src/types.md","lastUpdated":null}'),t={name:"source/src/types.md"};function l(p,s,h,k,r,o){return e(),i("div",null,s[0]||(s[0]=[n(`
A manifold is mathematically defined as a topological space that resembles Euclidean space locally.
In GeometryOps (and geodesy more generally), there are three manifolds we care about:
Planar: the 2d plane, a completely Euclidean manifold
Spherical: the unit sphere, but one where areas are multiplied by the radius of the Earth. This is not Euclidean globally, but all map projections attempt to represent the sphere on the Euclidean 2D plane to varying degrees of success.
Geodesic: the ellipsoid, the closest we can come to representing the Earth by a simple geometric shape. Parametrized by semimajor_axis and inv_flattening.
Generally, we aim to have Linear and Spherical be operable everywhere, whereas Geodesic will only apply in specific circumstances. Currently, those circumstances are area and segmentize, but this could be extended with time and https://github.com/JuliaGeo/SphericalGeodesics.jl.
julia
export Planar, Spherical, Geodesic
+export TraitTarget
+export BoolsAsTypes, _True, _False, _booltype
+
+"""
+ abstract type Manifold
+
+A manifold is mathematically defined as a topological space that resembles Euclidean space locally.
+
+We use the manifold definition to define the space in which an operation should be performed, or where a geometry lies.
+
+Currently we have \`Planar\`, \`Spherical\`, and \`Geodesic\` manifolds.
+"""
+abstract type Manifold end
+
+"""
+ Planar()
+
+A planar manifold refers to the 2D Euclidean plane.
+
+Z coordinates may be accepted but will not influence geometry calculations, which
+are done purely on 2D geometry. This is the standard "2.5D" model used by e.g. GEOS.
+"""
+struct Planar <: Manifold
+end
+
+"""
+ Spherical(; radius)
+
+A spherical manifold means that the geometry is on the 3-sphere (but is represented by 2-D longitude and latitude).
+
+By default, the radius is defined as the mean radius of the Earth, \`6371008.8 m\`.
+
+# Extended help
+
+!!! note
+ The traditional definition of spherical coordinates in physics and mathematics,
+ \`\`r, \\\\theta, \\\\phi\`\`, uses the _colatitude_, that measures angular displacement from the \`z\`-axis.
+
+ Here, we use the geographic definition of longitude and latitude, meaning
+ that \`lon\` is longitude between -180 and 180, and \`lat\` is latitude between
+ \`-90\` (south pole) and \`90\` (north pole).
+"""
+Base.@kwdef struct Spherical{T} <: Manifold
+ radius::T = 6371008.8
+end
+
+"""
+ Geodesic(; semimajor_axis, inv_flattening)
+
+A geodesic manifold means that the geometry is on a 3-dimensional ellipsoid, parameterized by \`semimajor_axis\` (\`\`a\`\` in mathematical parlance)
+and \`inv_flattening\` (\`\`1/f\`\`).
+
+Usually, this is only relevant for area and segmentization calculations. It becomes more relevant as one grows closer to the poles (or equator).
+"""
+Base.@kwdef struct Geodesic{T} <: Manifold
+ semimajor_axis::T = 6378137.0
+ inv_flattening::T = 298.257223563
+end
This struct holds a trait parameter or a union of trait parameters. It's essentially a way to construct unions.
julia
"""
+ 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)...}}()
+
+
+Base.in(::Trait, ::TraitTarget{Target}) where {Trait <: GI.AbstractTrait, Target} = Trait <: Target
In apply and applyreduce, 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.
TODO: should we switch to Static.jl?
julia
"""
+ abstract type BoolsAsTypes
+
+"""
+abstract type BoolsAsTypes end
+
+"""
+ struct _True <: BoolsAsTypes
+
+A struct that means \`true\`.
+"""
+struct _True <: BoolsAsTypes end
+
+"""
+ struct _False <: BoolsAsTypes
+
+A struct that means \`false\`.
+"""
+struct _False <: BoolsAsTypes end
+
+"""
+ _booltype(x)
+
+Returns a \`BoolsAsTypes\` from \`x\`, whether it's a boolean or a BoolsAsTypes.
+"""
+function _booltype end
+
+@inline _booltype(x::Bool)::BoolsAsTypes = x ? _True() : _False()
+@inline _booltype(x::BoolsAsTypes)::BoolsAsTypes = x
`,24)]))}const F=a(t,[["render",l]]);export{c as __pageData,F as default};
diff --git a/previews/PR239/assets/source_transformations_correction_closed_ring.md.DlzJm4wM.js b/previews/PR239/assets/source_transformations_correction_closed_ring.md.DlzJm4wM.js
new file mode 100644
index 000000000..95f4acd86
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_correction_closed_ring.md.DlzJm4wM.js
@@ -0,0 +1,30 @@
+import{_ as l,c as a,a5 as n,j as i,a as t,o as e}from"./chunks/framework.onQNwZ2I.js";const m=JSON.parse('{"title":"Closed Rings","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/correction/closed_ring.md","filePath":"source/transformations/correction/closed_ring.md","lastUpdated":null}'),h={name:"source/transformations/correction/closed_ring.md"},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={class:"MathJax",jax:"SVG",style:{direction:"ltr",position:"relative"}},o={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"};function d(g,s,c,E,y,u){return e(),a("div",null,[s[7]||(s[7]=n(`
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))])}const C=l(h,[["render",d]]);export{m as __pageData,C as default};
diff --git a/previews/PR239/assets/source_transformations_correction_closed_ring.md.DlzJm4wM.lean.js b/previews/PR239/assets/source_transformations_correction_closed_ring.md.DlzJm4wM.lean.js
new file mode 100644
index 000000000..95f4acd86
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_correction_closed_ring.md.DlzJm4wM.lean.js
@@ -0,0 +1,30 @@
+import{_ as l,c as a,a5 as n,j as i,a as t,o as e}from"./chunks/framework.onQNwZ2I.js";const m=JSON.parse('{"title":"Closed Rings","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/correction/closed_ring.md","filePath":"source/transformations/correction/closed_ring.md","lastUpdated":null}'),h={name:"source/transformations/correction/closed_ring.md"},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={class:"MathJax",jax:"SVG",style:{direction:"ltr",position:"relative"}},o={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"};function d(g,s,c,E,y,u){return e(),a("div",null,[s[7]||(s[7]=n(`
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))])}const C=l(h,[["render",d]]);export{m as __pageData,C as default};
diff --git a/previews/PR239/assets/source_transformations_correction_geometry_correction.md.DSGv3LiX.js b/previews/PR239/assets/source_transformations_correction_geometry_correction.md.DSGv3LiX.js
new file mode 100644
index 000000000..e79621afd
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_correction_geometry_correction.md.DSGv3LiX.js
@@ -0,0 +1,31 @@
+import{_ as r,c as o,a5 as e,j as i,a as t,G as n,B as l,o as p}from"./chunks/framework.onQNwZ2I.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}'),h={name:"source/transformations/correction/geometry_correction.md"},k={class:"jldocstring custom-block",open:""},c={class:"jldocstring custom-block",open:""},d={class:"jldocstring custom-block",open:""},y={class:"jldocstring custom-block",open:""},g={class:"jldocstring custom-block",open:""};function m(E,s,u,F,f,C){const a=l("Badge");return p(),o("div",null,[s[15]||(s[15]=e('
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.
',4))]),s[17]||(s[17]=i("hr",null,null,-1)),s[18]||(s[18]=i("p",null,[i("em",null,[t("This page was generated using "),i("a",{href:"https://github.com/fredrikekre/Literate.jl",target:"_blank",rel:"noreferrer"},"Literate.jl"),t(".")])],-1))])}const A=r(h,[["render",m]]);export{G as __pageData,A as default};
diff --git a/previews/PR239/assets/source_transformations_correction_geometry_correction.md.DSGv3LiX.lean.js b/previews/PR239/assets/source_transformations_correction_geometry_correction.md.DSGv3LiX.lean.js
new file mode 100644
index 000000000..e79621afd
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_correction_geometry_correction.md.DSGv3LiX.lean.js
@@ -0,0 +1,31 @@
+import{_ as r,c as o,a5 as e,j as i,a as t,G as n,B as l,o as p}from"./chunks/framework.onQNwZ2I.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}'),h={name:"source/transformations/correction/geometry_correction.md"},k={class:"jldocstring custom-block",open:""},c={class:"jldocstring custom-block",open:""},d={class:"jldocstring custom-block",open:""},y={class:"jldocstring custom-block",open:""},g={class:"jldocstring custom-block",open:""};function m(E,s,u,F,f,C){const a=l("Badge");return p(),o("div",null,[s[15]||(s[15]=e('
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.
',4))]),s[17]||(s[17]=i("hr",null,null,-1)),s[18]||(s[18]=i("p",null,[i("em",null,[t("This page was generated using "),i("a",{href:"https://github.com/fredrikekre/Literate.jl",target:"_blank",rel:"noreferrer"},"Literate.jl"),t(".")])],-1))])}const A=r(h,[["render",m]]);export{G as __pageData,A as default};
diff --git a/previews/PR239/assets/source_transformations_correction_intersecting_polygons.md.CLhMqjHy.js b/previews/PR239/assets/source_transformations_correction_intersecting_polygons.md.CLhMqjHy.js
new file mode 100644
index 000000000..440caed24
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_correction_intersecting_polygons.md.CLhMqjHy.js
@@ -0,0 +1,97 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const E=JSON.parse('{"title":"Intersecting Polygons","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/correction/intersecting_polygons.md","filePath":"source/transformations/correction/intersecting_polygons.md","lastUpdated":null}'),t={name:"source/transformations/correction/intersecting_polygons.md"};function h(p,s,e,k,r,g){return l(),a("div",null,s[0]||(s[0]=[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 requirement 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)]))}const d=i(t,[["render",h]]);export{E as __pageData,d as default};
diff --git a/previews/PR239/assets/source_transformations_correction_intersecting_polygons.md.CLhMqjHy.lean.js b/previews/PR239/assets/source_transformations_correction_intersecting_polygons.md.CLhMqjHy.lean.js
new file mode 100644
index 000000000..440caed24
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_correction_intersecting_polygons.md.CLhMqjHy.lean.js
@@ -0,0 +1,97 @@
+import{_ as i,c as a,a5 as n,o as l}from"./chunks/framework.onQNwZ2I.js";const E=JSON.parse('{"title":"Intersecting Polygons","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/correction/intersecting_polygons.md","filePath":"source/transformations/correction/intersecting_polygons.md","lastUpdated":null}'),t={name:"source/transformations/correction/intersecting_polygons.md"};function h(p,s,e,k,r,g){return l(),a("div",null,s[0]||(s[0]=[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 requirement 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)]))}const d=i(t,[["render",h]]);export{E as __pageData,d as default};
diff --git a/previews/PR239/assets/source_transformations_extent.md.CrI7_2Lj.js b/previews/PR239/assets/source_transformations_extent.md.CrI7_2Lj.js
new file mode 100644
index 000000000..6452b6fb3
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_extent.md.CrI7_2Lj.js
@@ -0,0 +1,13 @@
+import{_ as e,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const k=JSON.parse('{"title":"Extent embedding","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/extent.md","filePath":"source/transformations/extent.md","lastUpdated":null}'),i={name:"source/transformations/extent.md"};function l(p,s,r,h,d,o){return t(),a("div",null,s[0]||(s[0]=[n(`
"""
+ 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)]))}const g=e(i,[["render",l]]);export{k as __pageData,g as default};
diff --git a/previews/PR239/assets/source_transformations_extent.md.CrI7_2Lj.lean.js b/previews/PR239/assets/source_transformations_extent.md.CrI7_2Lj.lean.js
new file mode 100644
index 000000000..6452b6fb3
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_extent.md.CrI7_2Lj.lean.js
@@ -0,0 +1,13 @@
+import{_ as e,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const k=JSON.parse('{"title":"Extent embedding","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/extent.md","filePath":"source/transformations/extent.md","lastUpdated":null}'),i={name:"source/transformations/extent.md"};function l(p,s,r,h,d,o){return t(),a("div",null,s[0]||(s[0]=[n(`
"""
+ 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)]))}const g=e(i,[["render",l]]);export{k as __pageData,g as default};
diff --git a/previews/PR239/assets/source_transformations_flip.md.CbHFKr9B.js b/previews/PR239/assets/source_transformations_flip.md.CbHFKr9B.js
new file mode 100644
index 000000000..d979792ae
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_flip.md.CbHFKr9B.js
@@ -0,0 +1,22 @@
+import{_ as i,c as a,a5 as n,o as p}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Coordinate flipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/flip.md","filePath":"source/transformations/flip.md","lastUpdated":null}'),t={name:"source/transformations/flip.md"};function l(h,s,e,k,r,d){return p(),a("div",null,s[0]||(s[0]=[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)]))}const E=i(t,[["render",l]]);export{g as __pageData,E as default};
diff --git a/previews/PR239/assets/source_transformations_flip.md.CbHFKr9B.lean.js b/previews/PR239/assets/source_transformations_flip.md.CbHFKr9B.lean.js
new file mode 100644
index 000000000..d979792ae
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_flip.md.CbHFKr9B.lean.js
@@ -0,0 +1,22 @@
+import{_ as i,c as a,a5 as n,o as p}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"Coordinate flipping","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/flip.md","filePath":"source/transformations/flip.md","lastUpdated":null}'),t={name:"source/transformations/flip.md"};function l(h,s,e,k,r,d){return p(),a("div",null,s[0]||(s[0]=[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)]))}const E=i(t,[["render",l]]);export{g as __pageData,E as default};
diff --git a/previews/PR239/assets/source_transformations_forcedims.md._lugiyHg.js b/previews/PR239/assets/source_transformations_forcedims.md._lugiyHg.js
new file mode 100644
index 000000000..8d62b14bb
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_forcedims.md._lugiyHg.js
@@ -0,0 +1,5 @@
+import{_ as i,c as a,a5 as t,o as n}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/forcedims.md","filePath":"source/transformations/forcedims.md","lastUpdated":null}'),e={name:"source/transformations/forcedims.md"};function p(h,s,l,k,r,d){return n(),a("div",null,s[0]||(s[0]=[t(`
julia
function forcexy(geom)
+ return GO.apply(GO.GI.PointTrait(), geom) do point
+ (GI.x(point), GI.y(point))
+ end
+end
`,3)]))}const E=i(e,[["render",p]]);export{g as __pageData,E as default};
diff --git a/previews/PR239/assets/source_transformations_forcedims.md._lugiyHg.lean.js b/previews/PR239/assets/source_transformations_forcedims.md._lugiyHg.lean.js
new file mode 100644
index 000000000..8d62b14bb
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_forcedims.md._lugiyHg.lean.js
@@ -0,0 +1,5 @@
+import{_ as i,c as a,a5 as t,o as n}from"./chunks/framework.onQNwZ2I.js";const g=JSON.parse('{"title":"","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/forcedims.md","filePath":"source/transformations/forcedims.md","lastUpdated":null}'),e={name:"source/transformations/forcedims.md"};function p(h,s,l,k,r,d){return n(),a("div",null,s[0]||(s[0]=[t(`
julia
function forcexy(geom)
+ return GO.apply(GO.GI.PointTrait(), geom) do point
+ (GI.x(point), GI.y(point))
+ end
+end
`,3)]))}const E=i(e,[["render",p]]);export{g as __pageData,E as default};
diff --git a/previews/PR239/assets/source_transformations_reproject.md.DZgumE25.js b/previews/PR239/assets/source_transformations_reproject.md.DZgumE25.js
new file mode 100644
index 000000000..891cb589b
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_reproject.md.DZgumE25.js
@@ -0,0 +1 @@
+import{_ as i,c as a,a5 as e,o as n}from"./chunks/framework.onQNwZ2I.js";const c=JSON.parse('{"title":"Geometry reprojection","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/reproject.md","filePath":"source/transformations/reproject.md","lastUpdated":null}'),t={name:"source/transformations/reproject.md"};function p(l,s,r,h,k,o){return n(),a("div",null,s[0]||(s[0]=[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 reference system, as a GeoFormatTypes.jl object or a string.\n- `target_crs`: the target coordinate reference 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 retrievable 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)]))}const g=i(t,[["render",p]]);export{c as __pageData,g as default};
diff --git a/previews/PR239/assets/source_transformations_reproject.md.DZgumE25.lean.js b/previews/PR239/assets/source_transformations_reproject.md.DZgumE25.lean.js
new file mode 100644
index 000000000..891cb589b
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_reproject.md.DZgumE25.lean.js
@@ -0,0 +1 @@
+import{_ as i,c as a,a5 as e,o as n}from"./chunks/framework.onQNwZ2I.js";const c=JSON.parse('{"title":"Geometry reprojection","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/reproject.md","filePath":"source/transformations/reproject.md","lastUpdated":null}'),t={name:"source/transformations/reproject.md"};function p(l,s,r,h,k,o){return n(),a("div",null,s[0]||(s[0]=[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 reference system, as a GeoFormatTypes.jl object or a string.\n- `target_crs`: the target coordinate reference 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 retrievable 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)]))}const g=i(t,[["render",p]]);export{c as __pageData,g as default};
diff --git a/previews/PR239/assets/source_transformations_segmentize.md.DQ-jJDsI.js b/previews/PR239/assets/source_transformations_segmentize.md.DQ-jJDsI.js
new file mode 100644
index 000000000..83598bc44
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_segmentize.md.DQ-jJDsI.js
@@ -0,0 +1,161 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/xnfkjof.D5-bot8v.png",l="/GeometryOps.jl/previews/PR239/assets/eozeurm.DGf_4PiA.png",o=JSON.parse('{"title":"Segmentize","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/segmentize.md","filePath":"source/transformations/segmentize.md","lastUpdated":null}'),k={name:"source/transformations/segmentize.md"};function e(p,s,r,d,E,g){return h(),a("div",null,s[0]||(s[0]=[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 \`Geodesic\` 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 = Planar()], 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::Manifold = Planar()\`: The method to use for segmentizing the geometry. At the moment, only \`Planar\` (assumes a flat plane) and \`Geodesic\` (assumes geometry on the ellipsoidal Earth and uses Vincenty's formulae) are available.
+- \`geom\`: The geometry to segmentize. Must be a \`LineString\`, \`LinearRing\`, \`Polygon\`, \`MultiPolygon\`, or \`GeometryCollection\`, or some vector or table of those.
+- \`max_distance::Real\`: The maximum distance between vertices in the geometry. **Beware: for \`Planar\`, this is in the units of the geometry, but for \`Geodesic\` and \`Spherical\` it's in units of the radius of the sphere.**
+
+Returns a geometry of similar type to the input geometry, but resampled.
+"""
+function segmentize(geom; max_distance, threaded::Union{Bool, BoolsAsTypes} = _False())
+ return segmentize(Planar(), geom; max_distance, threaded = _booltype(threaded))
+end
`,39)]))}const F=i(k,[["render",e]]);export{o as __pageData,F as default};
diff --git a/previews/PR239/assets/source_transformations_segmentize.md.DQ-jJDsI.lean.js b/previews/PR239/assets/source_transformations_segmentize.md.DQ-jJDsI.lean.js
new file mode 100644
index 000000000..83598bc44
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_segmentize.md.DQ-jJDsI.lean.js
@@ -0,0 +1,161 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/xnfkjof.D5-bot8v.png",l="/GeometryOps.jl/previews/PR239/assets/eozeurm.DGf_4PiA.png",o=JSON.parse('{"title":"Segmentize","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/segmentize.md","filePath":"source/transformations/segmentize.md","lastUpdated":null}'),k={name:"source/transformations/segmentize.md"};function e(p,s,r,d,E,g){return h(),a("div",null,s[0]||(s[0]=[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 \`Geodesic\` 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 = Planar()], 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::Manifold = Planar()\`: The method to use for segmentizing the geometry. At the moment, only \`Planar\` (assumes a flat plane) and \`Geodesic\` (assumes geometry on the ellipsoidal Earth and uses Vincenty's formulae) are available.
+- \`geom\`: The geometry to segmentize. Must be a \`LineString\`, \`LinearRing\`, \`Polygon\`, \`MultiPolygon\`, or \`GeometryCollection\`, or some vector or table of those.
+- \`max_distance::Real\`: The maximum distance between vertices in the geometry. **Beware: for \`Planar\`, this is in the units of the geometry, but for \`Geodesic\` and \`Spherical\` it's in units of the radius of the sphere.**
+
+Returns a geometry of similar type to the input geometry, but resampled.
+"""
+function segmentize(geom; max_distance, threaded::Union{Bool, BoolsAsTypes} = _False())
+ return segmentize(Planar(), geom; max_distance, threaded = _booltype(threaded))
+end
`,39)]))}const F=i(k,[["render",e]]);export{o as __pageData,F as default};
diff --git a/previews/PR239/assets/source_transformations_simplify.md.CnWLEC8c.js b/previews/PR239/assets/source_transformations_simplify.md.CnWLEC8c.js
new file mode 100644
index 000000000..b2b60e12a
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_simplify.md.CnWLEC8c.js
@@ -0,0 +1,490 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const l="/GeometryOps.jl/previews/PR239/assets/evhqnlv.Bglvb-jp.png",k="/GeometryOps.jl/previews/PR239/assets/tsgqxnn.B94PsR1K.png",t="/GeometryOps.jl/previews/PR239/assets/umfmfiz.Da39FuJg.png",p="/GeometryOps.jl/previews/PR239/assets/twuyjor.DYrZOYql.png",c=JSON.parse('{"title":"Geometry simplification","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/simplify.md","filePath":"source/transformations/simplify.md","lastUpdated":null}'),e={name:"source/transformations/simplify.md"};function E(r,s,d,g,y,F){return h(),a("div",null,s[0]||(s[0]=[n(`
This file holds implementations for the RadialDistance, Douglas-Peucker, and Visvalingam-Whyatt algorithms for simplifying geometries (specifically for polygons and lines).
The GEOS extension also allows for GEOS's topology preserving simplification as well as Douglas-Peucker simplification implemented in GEOS. Call this by passing GEOS(; method = :TopologyPreserve) or GEOS(; method = :DouglasPeucker) to the algorithm.
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 decreasing 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 unnecessary 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 connecting 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 unnecessary 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
`,71)]))}const C=i(e,[["render",E]]);export{c as __pageData,C as default};
diff --git a/previews/PR239/assets/source_transformations_simplify.md.CnWLEC8c.lean.js b/previews/PR239/assets/source_transformations_simplify.md.CnWLEC8c.lean.js
new file mode 100644
index 000000000..b2b60e12a
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_simplify.md.CnWLEC8c.lean.js
@@ -0,0 +1,490 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const l="/GeometryOps.jl/previews/PR239/assets/evhqnlv.Bglvb-jp.png",k="/GeometryOps.jl/previews/PR239/assets/tsgqxnn.B94PsR1K.png",t="/GeometryOps.jl/previews/PR239/assets/umfmfiz.Da39FuJg.png",p="/GeometryOps.jl/previews/PR239/assets/twuyjor.DYrZOYql.png",c=JSON.parse('{"title":"Geometry simplification","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/simplify.md","filePath":"source/transformations/simplify.md","lastUpdated":null}'),e={name:"source/transformations/simplify.md"};function E(r,s,d,g,y,F){return h(),a("div",null,s[0]||(s[0]=[n(`
This file holds implementations for the RadialDistance, Douglas-Peucker, and Visvalingam-Whyatt algorithms for simplifying geometries (specifically for polygons and lines).
The GEOS extension also allows for GEOS's topology preserving simplification as well as Douglas-Peucker simplification implemented in GEOS. Call this by passing GEOS(; method = :TopologyPreserve) or GEOS(; method = :DouglasPeucker) to the algorithm.
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 decreasing 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 unnecessary 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 connecting 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 unnecessary 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
`,71)]))}const C=i(e,[["render",E]]);export{c as __pageData,C as default};
diff --git a/previews/PR239/assets/source_transformations_transform.md.BWclfchr.js b/previews/PR239/assets/source_transformations_transform.md.BWclfchr.js
new file mode 100644
index 000000000..4ece6c0b6
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_transform.md.BWclfchr.js
@@ -0,0 +1,55 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const F=JSON.parse('{"title":"Pointwise transformation","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/transform.md","filePath":"source/transformations/transform.md","lastUpdated":null}'),l={name:"source/transformations/transform.md"};function e(p,s,h,r,k,o){return t(),a("div",null,s[0]||(s[0]=[n(`
`,4)]))}const c=i(l,[["render",e]]);export{F as __pageData,c as default};
diff --git a/previews/PR239/assets/source_transformations_transform.md.BWclfchr.lean.js b/previews/PR239/assets/source_transformations_transform.md.BWclfchr.lean.js
new file mode 100644
index 000000000..4ece6c0b6
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_transform.md.BWclfchr.lean.js
@@ -0,0 +1,55 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const F=JSON.parse('{"title":"Pointwise transformation","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/transform.md","filePath":"source/transformations/transform.md","lastUpdated":null}'),l={name:"source/transformations/transform.md"};function e(p,s,h,r,k,o){return t(),a("div",null,s[0]||(s[0]=[n(`
`,4)]))}const c=i(l,[["render",e]]);export{F as __pageData,c as default};
diff --git a/previews/PR239/assets/source_transformations_tuples.md.BFXQMbxF.js b/previews/PR239/assets/source_transformations_tuples.md.BFXQMbxF.js
new file mode 100644
index 000000000..42ae74220
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_tuples.md.BFXQMbxF.js
@@ -0,0 +1,19 @@
+import{_ as a,c as n,a5 as i,o as e}from"./chunks/framework.onQNwZ2I.js";const d=JSON.parse('{"title":"Tuple conversion","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/tuples.md","filePath":"source/transformations/tuples.md","lastUpdated":null}'),t={name:"source/transformations/tuples.md"};function p(l,s,r,o,h,k){return e(),n("div",null,s[0]||(s[0]=[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)]))}const F=a(t,[["render",p]]);export{d as __pageData,F as default};
diff --git a/previews/PR239/assets/source_transformations_tuples.md.BFXQMbxF.lean.js b/previews/PR239/assets/source_transformations_tuples.md.BFXQMbxF.lean.js
new file mode 100644
index 000000000..42ae74220
--- /dev/null
+++ b/previews/PR239/assets/source_transformations_tuples.md.BFXQMbxF.lean.js
@@ -0,0 +1,19 @@
+import{_ as a,c as n,a5 as i,o as e}from"./chunks/framework.onQNwZ2I.js";const d=JSON.parse('{"title":"Tuple conversion","description":"","frontmatter":{},"headers":[],"relativePath":"source/transformations/tuples.md","filePath":"source/transformations/tuples.md","lastUpdated":null}'),t={name:"source/transformations/tuples.md"};function p(l,s,r,o,h,k){return e(),n("div",null,s[0]||(s[0]=[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)]))}const F=a(t,[["render",p]]);export{d as __pageData,F as default};
diff --git a/previews/PR239/assets/source_types.md.BzRqHlPc.js b/previews/PR239/assets/source_types.md.BzRqHlPc.js
new file mode 100644
index 000000000..9d5cfae61
--- /dev/null
+++ b/previews/PR239/assets/source_types.md.BzRqHlPc.js
@@ -0,0 +1,38 @@
+import{_ as i,c as a,a5 as n,o as e}from"./chunks/framework.onQNwZ2I.js";const E=JSON.parse('{"title":"Types","description":"","frontmatter":{},"headers":[],"relativePath":"source/types.md","filePath":"source/types.md","lastUpdated":null}'),t={name:"source/types.md"};function l(h,s,p,k,r,d){return e(),a("div",null,s[0]||(s[0]=[n(`
This file defines some fundamental types used in GeometryOps.
Warning
Unlike in other Julia packages, only some types are defined in this file, not all. This is because we define types in the files where they are used, to make it easier to understand the code.
GEOS is a struct which instructs the method it's passed to as an algorithm to use the appropriate GEOS function via LibGEOS.jl for the operation.
It's generally a lot slower than the native Julia implementations, but it's useful for two reasons:
Functionality which doesn't exist in GeometryOps can be accessed through the GeometryOps API, but use GEOS in the backend until someone implements a native Julia version.
It's a good way to test the correctness of the native implementations.
julia
"""
+ GEOS(; params...)
+
+A struct which instructs the method it's passed to as an algorithm
+to use the appropriate GEOS function via \`LibGEOS.jl\` for the operation.
+
+Dispatch is generally carried out using the names of the keyword arguments.
+For example, \`segmentize\` will only accept a \`GEOS\` struct with only a
+\`max_distance\` keyword, and no other.
+
+It's generally a lot slower than the native Julia implementations, since
+it must convert to the LibGEOS implementation and back - so be warned!
+"""
+struct GEOS
+ params::NamedTuple
+end
+
+function GEOS(; params...)
+ nt = NamedTuple(params)
+ return GEOS(nt)
+end
These are definitions for convenience, so we don't have to type out alg.params every time.
julia
Base.get(alg::GEOS, key, value) = Base.get(alg.params, key, value)
+Base.get(f::Function, alg::GEOS, key) = Base.get(f, alg.params, key)
+
+"""
+ enforce(alg::GO.GEOS, kw::Symbol, f)
+
+Enforce the presence of a keyword argument in a \`GEOS\` algorithm, and return \`alg.params[kw]\`.
+
+Throws an error if the key is not present, and mentions \`f\` in the error message (since there isn't
+a good way to get the name of the function that called this method).
+"""
+function enforce(alg::GEOS, kw::Symbol, f)
+ if haskey(alg.params, kw)
+ return alg.params[kw]
+ else
+ error("$(f) requires a \`$(kw)\` keyword argument to the \`GEOS\` algorithm, which was not provided.")
+ end
+end
`,13)]))}const g=i(t,[["render",l]]);export{E as __pageData,g as default};
diff --git a/previews/PR239/assets/source_types.md.BzRqHlPc.lean.js b/previews/PR239/assets/source_types.md.BzRqHlPc.lean.js
new file mode 100644
index 000000000..9d5cfae61
--- /dev/null
+++ b/previews/PR239/assets/source_types.md.BzRqHlPc.lean.js
@@ -0,0 +1,38 @@
+import{_ as i,c as a,a5 as n,o as e}from"./chunks/framework.onQNwZ2I.js";const E=JSON.parse('{"title":"Types","description":"","frontmatter":{},"headers":[],"relativePath":"source/types.md","filePath":"source/types.md","lastUpdated":null}'),t={name:"source/types.md"};function l(h,s,p,k,r,d){return e(),a("div",null,s[0]||(s[0]=[n(`
This file defines some fundamental types used in GeometryOps.
Warning
Unlike in other Julia packages, only some types are defined in this file, not all. This is because we define types in the files where they are used, to make it easier to understand the code.
GEOS is a struct which instructs the method it's passed to as an algorithm to use the appropriate GEOS function via LibGEOS.jl for the operation.
It's generally a lot slower than the native Julia implementations, but it's useful for two reasons:
Functionality which doesn't exist in GeometryOps can be accessed through the GeometryOps API, but use GEOS in the backend until someone implements a native Julia version.
It's a good way to test the correctness of the native implementations.
julia
"""
+ GEOS(; params...)
+
+A struct which instructs the method it's passed to as an algorithm
+to use the appropriate GEOS function via \`LibGEOS.jl\` for the operation.
+
+Dispatch is generally carried out using the names of the keyword arguments.
+For example, \`segmentize\` will only accept a \`GEOS\` struct with only a
+\`max_distance\` keyword, and no other.
+
+It's generally a lot slower than the native Julia implementations, since
+it must convert to the LibGEOS implementation and back - so be warned!
+"""
+struct GEOS
+ params::NamedTuple
+end
+
+function GEOS(; params...)
+ nt = NamedTuple(params)
+ return GEOS(nt)
+end
These are definitions for convenience, so we don't have to type out alg.params every time.
julia
Base.get(alg::GEOS, key, value) = Base.get(alg.params, key, value)
+Base.get(f::Function, alg::GEOS, key) = Base.get(f, alg.params, key)
+
+"""
+ enforce(alg::GO.GEOS, kw::Symbol, f)
+
+Enforce the presence of a keyword argument in a \`GEOS\` algorithm, and return \`alg.params[kw]\`.
+
+Throws an error if the key is not present, and mentions \`f\` in the error message (since there isn't
+a good way to get the name of the function that called this method).
+"""
+function enforce(alg::GEOS, kw::Symbol, f)
+ if haskey(alg.params, kw)
+ return alg.params[kw]
+ else
+ error("$(f) requires a \`$(kw)\` keyword argument to the \`GEOS\` algorithm, which was not provided.")
+ end
+end
`,13)]))}const g=i(t,[["render",l]]);export{E as __pageData,g as default};
diff --git a/previews/PR239/assets/source_utils.md.Cy9C-nnj.js b/previews/PR239/assets/source_utils.md.Cy9C-nnj.js
new file mode 100644
index 000000000..494fb3f1f
--- /dev/null
+++ b/previews/PR239/assets/source_utils.md.Cy9C-nnj.js
@@ -0,0 +1,120 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const d=JSON.parse('{"title":"Utility functions","description":"","frontmatter":{},"headers":[],"relativePath":"source/utils.md","filePath":"source/utils.md","lastUpdated":null}'),p={name:"source/utils.md"};function l(h,s,k,e,r,F){return t(),a("div",null,s[0]||(s[0]=[n(`
`,8)]))}const E=i(p,[["render",l]]);export{d as __pageData,E as default};
diff --git a/previews/PR239/assets/source_utils.md.Cy9C-nnj.lean.js b/previews/PR239/assets/source_utils.md.Cy9C-nnj.lean.js
new file mode 100644
index 000000000..494fb3f1f
--- /dev/null
+++ b/previews/PR239/assets/source_utils.md.Cy9C-nnj.lean.js
@@ -0,0 +1,120 @@
+import{_ as i,c as a,a5 as n,o as t}from"./chunks/framework.onQNwZ2I.js";const d=JSON.parse('{"title":"Utility functions","description":"","frontmatter":{},"headers":[],"relativePath":"source/utils.md","filePath":"source/utils.md","lastUpdated":null}'),p={name:"source/utils.md"};function l(h,s,k,e,r,F){return t(),a("div",null,s[0]||(s[0]=[n(`
# Geospatial packages from Julia
+import GeoInterface as GI
+import GeometryOps as GO
+import GeoFormatTypes as GFT
+using GeoJSON # to load some data
+# Packages for coordinate transformation and projection
+import CoordinateTransformations
+import Proj
+# Plotting
+using CairoMakie
+using GeoMakie
We can also create a single LinearRing trait, the building block of a polygon. A LinearRing is simply a LineString with the same beginning and endpoint, i.e., an arbitrary closed shape composed of point pairs.
Now, we can use GeometryOps and CoordinateTransformations to shift polygon1 up, to avoid plotting over our earlier results. This is done through the GeometryOps.transform function.
Polygons can contain "holes". The first LinearRing in a polygon is the exterior, and all subsequent LinearRings are treated as holes in the leading LinearRing.
GeoInterface offers the GI.getexterior(poly) and GI.gethole(poly) methods to get the exterior ring and an iterable of holes, respectively.
Great, now we can make Points, MultiPoints, Lines, LineStrings, Polygons (with holes), and MultiPolygons and modify them using [CoordinateTransformations] and [GeometryOps].
Plot geometries on a map using GeoMakie and coordinate reference system (CRS)
In geospatial sciences we often have data in one Coordinate Reference System (CRS) (source) and would like to display it in different (destination) CRS. GeoMakie allows us to do this by automatically projecting from source to destination CRS.
Here, our source CRS is common geographic (i.e. coordinates of latitude and longitude), WGS84.
julia
source_crs1 = GFT.EPSG(4326)
GeoFormatTypes.EPSG{1}((4326,))
Now let's pick a destination CRS for displaying our map. Here we'll pick natearth2.
julia
destination_crs = "+proj=natearth2"
"+proj=natearth2"
Let's add land area for context. First, download and open the Natural Earth global land polygons at 110 m resolution.GeoMakie ships with this particular dataset, so we will access it from there.
Natural Earth has lots of other datasets, and there is a Julia package that provides an interface to it called NaturalEarth.jl.
Read the land MultiPolygons as a GeoJSON.FeatureCollection.
julia
land_geo = GeoJSON.read(land_path)
FeatureCollection with 127 Features
We then need to create a figure with a GeoAxis that can handle the projection between source and destination CRS. For GeoMakie, source is the CRS of the input and dest is the CRS you want to visualize in.
Create geospatial geometries with embedded coordinate reference system information
Great, we can make geometries and plot them on a map... now let's export the data to common geospatial data formats. To do this we now need to create geometries with embedded CRS information, making it a geospatial geometry. All that's needed is to include ; crs = crs as a keyword argument when constructing the geometry.
Let's do this for a new Polygon
julia
r = 3;
+k = 7;
+ϴ = 0:0.01:2pi;
+x = r .* (k + 1) .* cos.(ϴ) .- r .* cos.((k + 1) .* ϴ);
+y = r .* (k + 1) .* sin.(ϴ) .- r .* sin.((k + 1) .* ϴ);
+ring4 = GI.LinearRing(Point.(zip(x, y)))
It is good practice to only include CRS information with the highest-level geometry. Not doing so can bloat the memory footprint of the geometry. CRS information can be included at the individual Point level but is discouraged.
And let's create second Polygon by shifting the first using CoordinateTransformations
Typically, you'll also want to include attributes with your geometries. Attributes are simply data that are attributed to each geometry. The easiest way to do this is to create a table with a :geometry column. Let's do this using DataFrames.
julia
using DataFrames
+df = DataFrame(geometry=[geopoly1, geopoly2])
Now let's add a couple of attributes to the geometries. We do this using DataFrames' ! mutation syntax that allows you to add a new column to an existing data frame.
There are Julia packages for most commonly used geographic data formats. Below, we show how to export that data to each of these.
We begin with GeoJSON, which is a JSON format for geospatial feature collections. It's human-readable and widely supported by most web-based and desktop geospatial libraries.
Now, let's save as a Shapefile. Shapefiles are actually a set of files (usually 4) that hold geometry information, a CRS, and additional attribute information as a separate table. When you give Shapefile.write a file name, it will write 4 files of the same name but with different extensions.
Now, let's save as a GeoParquet. GeoParquet is a geospatial extension to the Parquet format, which is a high-performance data store. It's great for storing large amounts of data in a single file.
Finally, if there's no Julia-native package that can write data to your desired format (e.g. .gpkg, .gml, etc), you can use GeoDataFrames. This package uses the GDAL library under the hood which supports writing to nearly all geospatial formats.
And there we go, you can now create mapped geometries from scratch, manipulate them, plot them on a map, and save them in multiple geospatial data formats.
`,120)]))}const A=i(y,[["render",F]]);export{G as __pageData,A as default};
diff --git a/previews/PR239/assets/tutorials_creating_geometry.md.BW0vmesq.lean.js b/previews/PR239/assets/tutorials_creating_geometry.md.BW0vmesq.lean.js
new file mode 100644
index 000000000..9097582fd
--- /dev/null
+++ b/previews/PR239/assets/tutorials_creating_geometry.md.BW0vmesq.lean.js
@@ -0,0 +1,89 @@
+import{_ as i,c as a,a5 as e,o as t}from"./chunks/framework.onQNwZ2I.js";const n="/GeometryOps.jl/previews/PR239/assets/tfqfmef.Dz86q2IX.png",l="/GeometryOps.jl/previews/PR239/assets/ivowqmu.Cx40vhB3.png",p="/GeometryOps.jl/previews/PR239/assets/xetmrwv.0OJvb21A.png",h="/GeometryOps.jl/previews/PR239/assets/cthossd.DaovVbE6.png",o="/GeometryOps.jl/previews/PR239/assets/bnkpkoa.rOsRk89v.png",k="/GeometryOps.jl/previews/PR239/assets/krkgpps.4wfjCtJV.png",r="/GeometryOps.jl/previews/PR239/assets/rleiuex.3sfpQl2i.png",g="/GeometryOps.jl/previews/PR239/assets/fyfzmss.Dab1-ETk.png",d="/GeometryOps.jl/previews/PR239/assets/mtwzvwz.D9AE7i2o.png",E="/GeometryOps.jl/previews/PR239/assets/tstphwa.DTKLkKh_.png",c="/GeometryOps.jl/previews/PR239/assets/wjwdigs.0f3Lq4Lw.png",G=JSON.parse('{"title":"Creating Geometry","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/creating_geometry.md","filePath":"tutorials/creating_geometry.md","lastUpdated":null}'),y={name:"tutorials/creating_geometry.md"};function F(u,s,f,C,m,b){return t(),a("div",null,s[0]||(s[0]=[e(`
# Geospatial packages from Julia
+import GeoInterface as GI
+import GeometryOps as GO
+import GeoFormatTypes as GFT
+using GeoJSON # to load some data
+# Packages for coordinate transformation and projection
+import CoordinateTransformations
+import Proj
+# Plotting
+using CairoMakie
+using GeoMakie
We can also create a single LinearRing trait, the building block of a polygon. A LinearRing is simply a LineString with the same beginning and endpoint, i.e., an arbitrary closed shape composed of point pairs.
Now, we can use GeometryOps and CoordinateTransformations to shift polygon1 up, to avoid plotting over our earlier results. This is done through the GeometryOps.transform function.
Polygons can contain "holes". The first LinearRing in a polygon is the exterior, and all subsequent LinearRings are treated as holes in the leading LinearRing.
GeoInterface offers the GI.getexterior(poly) and GI.gethole(poly) methods to get the exterior ring and an iterable of holes, respectively.
Great, now we can make Points, MultiPoints, Lines, LineStrings, Polygons (with holes), and MultiPolygons and modify them using [CoordinateTransformations] and [GeometryOps].
Plot geometries on a map using GeoMakie and coordinate reference system (CRS)
In geospatial sciences we often have data in one Coordinate Reference System (CRS) (source) and would like to display it in different (destination) CRS. GeoMakie allows us to do this by automatically projecting from source to destination CRS.
Here, our source CRS is common geographic (i.e. coordinates of latitude and longitude), WGS84.
julia
source_crs1 = GFT.EPSG(4326)
GeoFormatTypes.EPSG{1}((4326,))
Now let's pick a destination CRS for displaying our map. Here we'll pick natearth2.
julia
destination_crs = "+proj=natearth2"
"+proj=natearth2"
Let's add land area for context. First, download and open the Natural Earth global land polygons at 110 m resolution.GeoMakie ships with this particular dataset, so we will access it from there.
Natural Earth has lots of other datasets, and there is a Julia package that provides an interface to it called NaturalEarth.jl.
Read the land MultiPolygons as a GeoJSON.FeatureCollection.
julia
land_geo = GeoJSON.read(land_path)
FeatureCollection with 127 Features
We then need to create a figure with a GeoAxis that can handle the projection between source and destination CRS. For GeoMakie, source is the CRS of the input and dest is the CRS you want to visualize in.
Create geospatial geometries with embedded coordinate reference system information
Great, we can make geometries and plot them on a map... now let's export the data to common geospatial data formats. To do this we now need to create geometries with embedded CRS information, making it a geospatial geometry. All that's needed is to include ; crs = crs as a keyword argument when constructing the geometry.
Let's do this for a new Polygon
julia
r = 3;
+k = 7;
+ϴ = 0:0.01:2pi;
+x = r .* (k + 1) .* cos.(ϴ) .- r .* cos.((k + 1) .* ϴ);
+y = r .* (k + 1) .* sin.(ϴ) .- r .* sin.((k + 1) .* ϴ);
+ring4 = GI.LinearRing(Point.(zip(x, y)))
It is good practice to only include CRS information with the highest-level geometry. Not doing so can bloat the memory footprint of the geometry. CRS information can be included at the individual Point level but is discouraged.
And let's create second Polygon by shifting the first using CoordinateTransformations
Typically, you'll also want to include attributes with your geometries. Attributes are simply data that are attributed to each geometry. The easiest way to do this is to create a table with a :geometry column. Let's do this using DataFrames.
julia
using DataFrames
+df = DataFrame(geometry=[geopoly1, geopoly2])
Now let's add a couple of attributes to the geometries. We do this using DataFrames' ! mutation syntax that allows you to add a new column to an existing data frame.
There are Julia packages for most commonly used geographic data formats. Below, we show how to export that data to each of these.
We begin with GeoJSON, which is a JSON format for geospatial feature collections. It's human-readable and widely supported by most web-based and desktop geospatial libraries.
Now, let's save as a Shapefile. Shapefiles are actually a set of files (usually 4) that hold geometry information, a CRS, and additional attribute information as a separate table. When you give Shapefile.write a file name, it will write 4 files of the same name but with different extensions.
Now, let's save as a GeoParquet. GeoParquet is a geospatial extension to the Parquet format, which is a high-performance data store. It's great for storing large amounts of data in a single file.
Finally, if there's no Julia-native package that can write data to your desired format (e.g. .gpkg, .gml, etc), you can use GeoDataFrames. This package uses the GDAL library under the hood which supports writing to nearly all geospatial formats.
And there we go, you can now create mapped geometries from scratch, manipulate them, plot them on a map, and save them in multiple geospatial data formats.
`,120)]))}const A=i(y,[["render",F]]);export{G as __pageData,A as default};
diff --git a/previews/PR239/assets/tutorials_geodesic_paths.md.BlU0MlUq.js b/previews/PR239/assets/tutorials_geodesic_paths.md.BlU0MlUq.js
new file mode 100644
index 000000000..020af8870
--- /dev/null
+++ b/previews/PR239/assets/tutorials_geodesic_paths.md.BlU0MlUq.js
@@ -0,0 +1,11 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/chihpsx.CPClNl7F.png",o=JSON.parse('{"title":"Geodesic paths","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/geodesic_paths.md","filePath":"tutorials/geodesic_paths.md","lastUpdated":null}'),p={name:"tutorials/geodesic_paths.md"};function k(l,s,e,E,r,d){return h(),a("div",null,s[0]||(s[0]=[n(`
Geodesic paths are paths computed on an ellipsoid, as opposed to a plane.
julia
import GeometryOps as GO, GeoInterface as GI
+using CairoMakie, GeoMakie
+
+
+IAH = (-95.358421, 29.749907)
+AMS = (4.897070, 52.377956)
+
+
+fig, ga, _cp = lines(GeoMakie.coastlines(); axis = (; type = GeoAxis))
+lines!(ga, GO.segmentize(GO.GeodesicSegments(; max_distance = 100_000), GI.LineString([IAH, AMS])); color = Makie.wong_colors()[2])
+fig
',4)]))}const y=i(p,[["render",k]]);export{o as __pageData,y as default};
diff --git a/previews/PR239/assets/tutorials_geodesic_paths.md.BlU0MlUq.lean.js b/previews/PR239/assets/tutorials_geodesic_paths.md.BlU0MlUq.lean.js
new file mode 100644
index 000000000..020af8870
--- /dev/null
+++ b/previews/PR239/assets/tutorials_geodesic_paths.md.BlU0MlUq.lean.js
@@ -0,0 +1,11 @@
+import{_ as i,c as a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const t="/GeometryOps.jl/previews/PR239/assets/chihpsx.CPClNl7F.png",o=JSON.parse('{"title":"Geodesic paths","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/geodesic_paths.md","filePath":"tutorials/geodesic_paths.md","lastUpdated":null}'),p={name:"tutorials/geodesic_paths.md"};function k(l,s,e,E,r,d){return h(),a("div",null,s[0]||(s[0]=[n(`
Geodesic paths are paths computed on an ellipsoid, as opposed to a plane.
julia
import GeometryOps as GO, GeoInterface as GI
+using CairoMakie, GeoMakie
+
+
+IAH = (-95.358421, 29.749907)
+AMS = (4.897070, 52.377956)
+
+
+fig, ga, _cp = lines(GeoMakie.coastlines(); axis = (; type = GeoAxis))
+lines!(ga, GO.segmentize(GO.GeodesicSegments(; max_distance = 100_000), GI.LineString([IAH, AMS])); color = Makie.wong_colors()[2])
+fig
',4)]))}const y=i(p,[["render",k]]);export{o as __pageData,y as default};
diff --git a/previews/PR239/assets/tutorials_spatial_joins.md.B67GghbG.js b/previews/PR239/assets/tutorials_spatial_joins.md.B67GghbG.js
new file mode 100644
index 000000000..2a0e89af6
--- /dev/null
+++ b/previews/PR239/assets/tutorials_spatial_joins.md.B67GghbG.js
@@ -0,0 +1,52 @@
+import{_ as l,c as t,j as i,a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const e="/GeometryOps.jl/previews/PR239/assets/kojydpc.3UVIT8DR.png",p="/GeometryOps.jl/previews/PR239/assets/izslanu.Cm_V2Vs0.png",k="/GeometryOps.jl/previews/PR239/assets/cfoowuw.BEoJ_XVP.png",C=JSON.parse('{"title":"Spatial joins","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/spatial_joins.md","filePath":"tutorials/spatial_joins.md","lastUpdated":null}'),r={name:"tutorials/spatial_joins.md"},E={class:"MathJax",jax:"SVG",style:{direction:"ltr",position:"relative"}},d={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"};function o(g,s,y,F,c,u){return h(),t("div",null,[s[12]||(s[12]=i("h1",{id:"Spatial-joins",tabindex:"-1"},[a("Spatial joins "),i("a",{class:"header-anchor",href:"#Spatial-joins","aria-label":'Permalink to "Spatial joins {#Spatial-joins}"'},"")],-1)),i("p",null,[s[2]||(s[2]=a("Spatial joins are ")),s[3]||(s[3]=i("a",{href:"https://www.geeksforgeeks.org/sql-join-set-1-inner-left-right-and-full-joins/",target:"_blank",rel:"noreferrer"},"table joins",-1)),s[4]||(s[4]=a(" which are based not on equality, but on some predicate ")),i("mjx-container",E,[(h(),t("svg",d,s[0]||(s[0]=[n('',1)]))),s[1]||(s[1]=i("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"}},[i("math",{xmlns:"http://www.w3.org/1998/Math/MathML"},[i("mi",null,"p"),i("mo",{stretchy:"false"},"("),i("mi",null,"x"),i("mo",null,","),i("mi",null,"y"),i("mo",{stretchy:"false"},")")])],-1))]),s[5]||(s[5]=a(", which takes two geometries, and returns a value of either ")),s[6]||(s[6]=i("code",null,"true",-1)),s[7]||(s[7]=a(" or ")),s[8]||(s[8]=i("code",null,"false",-1)),s[9]||(s[9]=a(". For geometries, the ")),s[10]||(s[10]=i("a",{href:"https://en.wikipedia.org/wiki/DE-9IM",target:"_blank",rel:"noreferrer"},[i("code",null,"DE-9IM")],-1)),s[11]||(s[11]=a(" spatial relationship model is used to determine the spatial relationship between two geometries."))]),s[13]||(s[13]=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, for any kind of table join operation:
julia
using FlexiJoins
+innerjoin((table1, table1),
+ by_pred(:table1_column, predicate_function, :table2_column) # & add other conditions here
+)
+leftjoin((table1, table1),
+ by_pred(:table1_column, predicate_function, :table2_column) # & add other conditions here
+)
+rightjoin((table1, table1),
+ by_pred(:table1_column, predicate_function, :table2_column) # & add other conditions here
+)
+outerjoin((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))])}const T=l(r,[["render",o]]);export{C as __pageData,T as default};
diff --git a/previews/PR239/assets/tutorials_spatial_joins.md.B67GghbG.lean.js b/previews/PR239/assets/tutorials_spatial_joins.md.B67GghbG.lean.js
new file mode 100644
index 000000000..2a0e89af6
--- /dev/null
+++ b/previews/PR239/assets/tutorials_spatial_joins.md.B67GghbG.lean.js
@@ -0,0 +1,52 @@
+import{_ as l,c as t,j as i,a,a5 as n,o as h}from"./chunks/framework.onQNwZ2I.js";const e="/GeometryOps.jl/previews/PR239/assets/kojydpc.3UVIT8DR.png",p="/GeometryOps.jl/previews/PR239/assets/izslanu.Cm_V2Vs0.png",k="/GeometryOps.jl/previews/PR239/assets/cfoowuw.BEoJ_XVP.png",C=JSON.parse('{"title":"Spatial joins","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/spatial_joins.md","filePath":"tutorials/spatial_joins.md","lastUpdated":null}'),r={name:"tutorials/spatial_joins.md"},E={class:"MathJax",jax:"SVG",style:{direction:"ltr",position:"relative"}},d={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"};function o(g,s,y,F,c,u){return h(),t("div",null,[s[12]||(s[12]=i("h1",{id:"Spatial-joins",tabindex:"-1"},[a("Spatial joins "),i("a",{class:"header-anchor",href:"#Spatial-joins","aria-label":'Permalink to "Spatial joins {#Spatial-joins}"'},"")],-1)),i("p",null,[s[2]||(s[2]=a("Spatial joins are ")),s[3]||(s[3]=i("a",{href:"https://www.geeksforgeeks.org/sql-join-set-1-inner-left-right-and-full-joins/",target:"_blank",rel:"noreferrer"},"table joins",-1)),s[4]||(s[4]=a(" which are based not on equality, but on some predicate ")),i("mjx-container",E,[(h(),t("svg",d,s[0]||(s[0]=[n('',1)]))),s[1]||(s[1]=i("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"}},[i("math",{xmlns:"http://www.w3.org/1998/Math/MathML"},[i("mi",null,"p"),i("mo",{stretchy:"false"},"("),i("mi",null,"x"),i("mo",null,","),i("mi",null,"y"),i("mo",{stretchy:"false"},")")])],-1))]),s[5]||(s[5]=a(", which takes two geometries, and returns a value of either ")),s[6]||(s[6]=i("code",null,"true",-1)),s[7]||(s[7]=a(" or ")),s[8]||(s[8]=i("code",null,"false",-1)),s[9]||(s[9]=a(". For geometries, the ")),s[10]||(s[10]=i("a",{href:"https://en.wikipedia.org/wiki/DE-9IM",target:"_blank",rel:"noreferrer"},[i("code",null,"DE-9IM")],-1)),s[11]||(s[11]=a(" spatial relationship model is used to determine the spatial relationship between two geometries."))]),s[13]||(s[13]=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, for any kind of table join operation:
julia
using FlexiJoins
+innerjoin((table1, table1),
+ by_pred(:table1_column, predicate_function, :table2_column) # & add other conditions here
+)
+leftjoin((table1, table1),
+ by_pred(:table1_column, predicate_function, :table2_column) # & add other conditions here
+)
+rightjoin((table1, table1),
+ by_pred(:table1_column, predicate_function, :table2_column) # & add other conditions here
+)
+outerjoin((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).
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/PR239/explanations/peculiarities.html b/previews/PR239/explanations/peculiarities.html
new file mode 100644
index 000000000..7770e104e
--- /dev/null
+++ b/previews/PR239/explanations/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/PR239/explanations/winding_order.html b/previews/PR239/explanations/winding_order.html
new file mode 100644
index 000000000..d503ae661
--- /dev/null
+++ b/previews/PR239/explanations/winding_order.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!
GeometryOps' docs are divided into three main sections: tutorials, explanations and source code. Documentation and examples for many functions can be found in the source code section, since we use literate programming in GeometryOps.
Tutorials are meant to teach the fundamental concepts behind GeometryOps, and how to perform certain operations.
Explanations usually contain little code, and explain in more detail how GeometryOps works.
Source code usually contains explanations and examples at the top of the page, followed by annotated source code from that file.
+
+
+
+
\ No newline at end of file
diff --git a/previews/PR239/introduction.html b/previews/PR239/introduction.html
new file mode 100644
index 000000000..7fa3333df
--- /dev/null
+++ b/previews/PR239/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!
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__()
FlexiJoins.supports_mode(::FlexiJoins.Mode.NestedLoopFast, ::FlexiJoins.ByPred{F}, datas) where F <: GO_DE9IM_FUNCS = true
This method allows you to cache a tree, which we do by using an STRtree. TODO: wrap GO predicate functions in a TreeJoiner struct or something, to indicate that we want to use trees, since they can be slower in some situations.
julia
FlexiJoins.supports_mode(::FlexiJoins.Mode.Tree, ::FlexiJoins.ByPred{F}, datas) where F <: GO_DE9IM_FUNCS = true
Nested loop support is simple, and needs no further support. However, for trees, we need to define how the tree is prepared and how it is used. This is done by defining the prepare_for_join function to return an STRTree, and by defining the findmatchix function as querying that tree before checking intersections.
In theory, one could extract the tree from e.g a GeoPackage or some future GeoDataFrame.
julia
FlexiJoins.prepare_for_join(::FlexiJoins.Mode.Tree, X, cond::FlexiJoins.ByPred{<: GO_DE9IM_FUNCS}) = (X, SortTileRecursiveTree.STRtree(map(cond.Rf, X)))
+function FlexiJoins.findmatchix(::FlexiJoins.Mode.Tree, cond::FlexiJoins.ByPred{F}, ix_a, a, (B, tree)::Tuple, multi::typeof(identity)) where F <: GO_DE9IM_FUNCS
Implementation note: here, a is a row, and b is the full table. We extract the relevant columns using cond.Lf and cond.Rf.
julia
idxs = SortTileRecursiveTree.query(tree, cond.Lf(a))
+ intersecting_idxs = filter!(idxs) do idx
+ cond.pred(cond.Lf(a), cond.Rf(B[idx]))
+ end
+ return intersecting_idxs
+end
Finally, for completeness, we define the swap_sides function for those predicates which are defined as inversions.
module GeometryOpsLibGEOSExt
+
+import GeometryOps as GO, LibGEOS as LG
+import GeoInterface as GI
+
+import GeometryOps: GEOS, enforce, _True, _False, _booltype
+
+using GeometryOps
The filter statement is required because in Julia, each module has its own versions of these functions, which serve to evaluate or include code inside the scope of the module. However, if you import those from another module (which you would with all=true), that creates an ambiguity which causes a warning during precompile/load time. In order to avoid this, we filter out these special functions.
julia
for name in filter(!in((:var"#eval", :eval, :var"#include", :include)), names(GeometryOps))
+ @eval import GeometryOps: $name
+end
+
+"""
+ _wrap(geom; crs, calc_extent)
+
+Wraps `geom` in a GI wrapper geometry of its geometry trait. This allows us
+to attach CRS and extent info to geometry types which otherwise could not hold
+those, like LibGEOS and WKB geometries.
+
+Returns a GI wrapper geometry, for which `parent(result) == geom`.
+"""
+function _wrap(geom; crs=GI.crs(geom), calc_extent = true)
+ return GI.geointerface_geomtype(GI.geomtrait(geom))(geom; crs, extent = GI.extent(geom, calc_extent))
+end
+
+include("buffer.jl")
+include("segmentize.jl")
+include("simplify.jl")
+
+include("simple_overrides.jl")
+
+end
TODO: should this just be a target on GI.AbstractGeometryTrait()? But Geos doesn't support eg RectangleTrait Maybe we need an abstract trait GI.AbstractWKBGeomTrait?
This file contains simple overrides for GEOS, essentially only those functions which have direct counterparts in LG and only require conversion before calling.
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 polygon 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 polygon, 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 positive 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 slightly 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!
Below is an error handler similar to the others we have for e.g. segmentize, which checks if there is a method error for the geos backend.
Add an error hint for buffer if LibGEOS is not loaded!
julia
function _buffer_error_hinter(io, exc, argtypes, kwargs)
+ if isnothing(Base.get_extension(GeometryOps, :GeometryOpsLibGEOSExt)) && exc.f == buffer && first(argtypes) == GEOS
+ print(io, "\n\nThe `buffer` method requires the LibGEOS.jl package to be explicitly loaded.\n")
+ print(io, "You can do this by simply typing ")
+ printstyled(io, "using LibGEOS"; color = :cyan, bold = true)
+ println(io, " in your REPL, \nor otherwise loading LibGEOS.jl via using or import.")
+ end
+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 available 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 indices 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 indices 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 neighbor 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 polygons with no crossing intersection points, either one polygon is inside of another, or they are separate 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
+ curr_hole = _linearring(curr_hole)
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 completely 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 completely 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 original 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 approximately 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-coordinates 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 categorize 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 (default 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))
+ #= Removing intersections of `multipoly_a`` with pieces of `multipoly_b`` - as
+ pieces of `multipolygon_a`` are removed, continue to take difference with new shape
+ `polys` =#
+ polys = if i == 1
+ difference(multipoly_a, poly_b; target, fix_multipoly)
+ else
+ difference(GI.MultiPolygon(polys), poly_b; target, fix_multipoly)
+ end
+ #= One multipoly_a has been completely covered (and thus removed) there is no need to
+ continue taking the difference =#
+ isempty(polys) && break
+ 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` (collinear 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
+polygon 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, [T::Type])
+
+Return a list of intersection tuple points between two geometries. If no intersection points
+exist, returns an empty list.
+
+# 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_points(line1, line2)
output
julia
1-element Vector{Tuple{Float64, Float64}}:
+ (125.58375366067548, -14.83572303404496)
+"""
+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, including line
+segments, line strings, linear rings, polygons, and multipolygons. =#
+function _intersection_points(::Type{T}, ::GI.AbstractTrait, a, ::GI.AbstractTrait, b; exact = _True()) where T
Initialize an empty list of points
julia
result = Tuple{T, T}[]
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
julia
edges_a, edges_b = map(sort! ∘ to_edges, (a, b))
Loop over pairs of edges and add any unique intersection points to results
julia
for a_edge in edges_a, b_edge in edges_b
+ line_orient, intr1, intr2 = _intersection_point(T, a_edge, b_edge; exact)
+ line_orient == line_out && continue # no intersection points
+ pt1, _ = intr1
+ push!(result, pt1) # if not line_out, there is at least one intersection point
+ if line_orient == line_over # if line_over, there are two intersection points
+ pt2, _ = intr2
+ push!(result, pt2)
+ end
+ end
+ #= TODO: We might be able to just add unique points with checks on the α and β values
+ returned from `_intersection_point`, but this would be different for curves vs polygons
+ vs multipolygons depending on if the shape is closed. This then wouldn't allow using the
+ `to_edges` functionality. =#
+ unique!(sort!(result))
+ 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 calculated 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
+ inaccuracies, α and β calculations may yield 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 certainly 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([_linearring(tuples(ext_b))]))
+ elseif b_in_a
+ push!(polys, GI.Polygon([_linearring(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))))
+ ih = _linearring(ih)
+ 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 completely 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 polygon 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
The convex hull of a set of points is the smallest convex polygon that contains all the points.
GeometryOps.jl provides a number of methods for computing the convex hull of a set of points, usually linked to other Julia packages.
For now, we expose one algorithm, MonotoneChainMethod, which uses the DelaunayTriangulation.jl package. The GEOS() interface also supports convex hulls.
Future work could include other algorithms, such as Quickhull.jl, or similar, via package extensions.
import GeometryOps as GO, GeoInterface as GI
+using CairoMakie # to plot
+using NaturalEarth # for data
+
+all_adm0 = naturalearth("admin_0_countries", 110)
+usa = all_adm0.geometry[findfirst(==("USA"), all_adm0.ADM0_A3)]
+f, a, p = lines(usa)
+lines!(a, GO.convex_hull(usa); color = Makie.wong_colors()[2])
+f
The winding order of the monotone chain method is counterclockwise, while the winding order of the GEOS method is clockwise.
GeometryOps' convexity detection says that the GEOS hull is convex, while the monotone chain method hull is not. However, they are both going over the same points (we checked), it's just that the winding order is different.
In reality, both sets are convex, but we need to fix the GeometryOps convexity detector (isconcave)!
We may also decide at a later date to change the returned winding order of the polygon, but most algorithms are robust to that, and you can always fix it...
julia
import GeoInterface as GI, GeometryOps as GO, LibGEOS as LG
+using CairoMakie # to plot
+
+points = rand(Point2{Float64}, 100)
+go_hull = GO.convex_hull(GO.MonotoneChainMethod(), points)
+lg_hull = GO.convex_hull(GO.GEOS(), points)
+
+fig = Figure()
+a1, p1 = lines(fig[1, 1], go_hull; color = 1:GI.npoint(go_hull), axis = (; title = "MonotoneChainMethod()"))
+a2, p2 = lines(fig[2, 1], lg_hull; color = 1:GI.npoint(lg_hull), axis = (; title = "GEOS()"))
+cb = Colorbar(fig[1:2, 2], p1; label = "Vertex number")
+fig
"""
+ convex_hull([method], geometries)
+
+Compute the convex hull of the points in `geometries`.
+Returns a `GI.Polygon` representing the convex hull.
+
+Note that the polygon returned is wound counterclockwise
+as in the Simple Features standard by default. If you
+choose GEOS, the winding order will be inverted.
+
+!!! warning
+ This interface only computes the 2-dimensional convex hull!
+
+ For higher dimensional hulls, use the relevant package (Qhull.jl, Quickhull.jl, or similar).
+"""
+function convex_hull end
+
+"""
+ MonotoneChainMethod()
+
+This is an algorithm for the `convex_hull` function.
+
+Uses [`DelaunayTriangulation.jl`](https://github.com/JuliaGeometry/DelaunayTriangulation.jl) to compute the convex hull.
+This is a pure Julia algorithm which provides an optimal Delaunay triangulation.
+
+See also `convex_hull`
+"""
+struct MonotoneChainMethod end
GrahamScanMethod, etc. can be implemented in GO as well, if someone wants to. If we add an extension on Quickhull.jl, then that would be another algorithm.
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 positive 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 common 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 explicitly 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 definition.
+"""
+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 definition, 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 definition, 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 completely contains another geometry, or in other words, that the second geometry is completely 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, including 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, including 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 completely 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 geometry'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 boundary 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 requirements, 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 completely 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 requirements, 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 boundary 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 requirements, 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 separates 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 boundaries. 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 collinear.
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 automatically 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 respectively, 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 collinear 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 collinear 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 geometry's 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 geometry's 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 boundary point interacts with
+the boundary 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 boundary 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 boundary 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 boundary points interacts
+with the polygon's boundary 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` if the line goes clockwise, or `false` if the line goes
+counter-clockwise. "Going clockwise" means, mathematically,
+
+```math
+\\left(\\sum_{i=2}^n (x_i - x_{i-1}) \\cdot (y_i + y_{i-1})\\right) > 0
+```
+
+# Example
+
+```julia
+julia> import GeoInterface as GI, GeometryOps as GO
+julia> ring = GI.LinearRing([(0, 0), (1, 1), (1, 0), (0, 0)]);
+julia> 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 polygons 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 empty 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
All of the functions in this file are not implemented in Julia yet. Some of them may have implementations in LibGEOS which we can use via an extension, but there is no native-Julia implementation for them.
julia
function symdifference end
+function buffer end
+function convexhull end
+function concavehull end
module GeometryOpsCore
+
+using Base.Threads: nthreads, @threads, @spawn
+
+import GeoInterface
+import GeoInterface as GI
+import GeoInterface: Extents
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
+
+using Tables
+using DataAPI
+
+include("keyword_docs.jl")
+include("types.jl")
+
+include("apply.jl")
+include("applyreduce.jl")
+include("other_primitives.jl")
+include("geometry_utils.jl")
+
+end
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. Then, the geometry or structure is rebuilt.
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.
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
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.
Finally, we ensure that metadata is propagated correctly. This can only happen if the original table supports metadata reads, and the result supports metadata writes.
julia
if DataAPI.metadatasupport(typeof(result)).write
Copy over all metadata from the original table to the new table, if the original table supports metadata reading.
julia
if DataAPI.metadatasupport(IterableType).read
+ for (key, (value, style)) in DataAPI.metadata(iterable; style = true)
Default styles are not preserved on data transformation, so we must skip them!
julia
style == :default && continue
We assume that any other style is preserved.
julia
DataAPI.metadata!(result, key, value; style)
+ end
+ end
We don't usually care about the original table's metadata for GEOINTERFACE namespaced keys, so we should set the crs and geometrycolumns metadata if they are present. Ensure that GEOINTERFACE:geometrycolumns and GEOINTERFACE:crs are set!
julia
mdk = DataAPI.metadatakeys(result)
If the user has asked for geometry columns to persist, they would be here, so we don't need to set them.
julia
if !("GEOINTERFACE:geometrycolumns" in mdk)
If the geometry columns are not already set, we need to set them.
julia
DataAPI.metadata!(result, "GEOINTERFACE:geometrycolumns", (geometry_column,); style = :default)
+ end
Force reset CRS always, since you can pass crs to apply.
julia
new_crs = if haskey(kw, :crs)
+ kw[:crs]
+ else
+ GI.crs(iterable) # this will automatically check `GEOINTERFACE:crs` unless the type has a specialized implementation.
+ end
+
+ DataAPI.metadata!(result, "GEOINTERFACE:crs", new_crs; style = :default)
+ end
+
+ return result
+end
Rewrap all FeatureCollectionTrait feature collections as GI.FeatureCollection Maybe use threads to call _apply on component features
julia
@inline function _apply(f::F, target, ::GI.FeatureCollectionTrait, fc;
+ crs=GI.crs(fc), calc_extent=_False(), threaded
+) where F
Run _apply on all features in the feature collection, possibly threaded
julia
apply_to_feature(i) =
+ _apply(f, target, GI.getfeature(fc, i); crs, calc_extent, threaded=_False())::GI.Feature
+ features = _maptasks(apply_to_feature, 1:GI.nfeature(fc), threaded)
+ if calc_extent isa _True
Return a new geometry of 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
+
+
+### `_maptasks` - flexible, threaded `map`
+
+using Base.Threads: nthreads, @threads, @spawn
Threading utility, modified Mason Protters threading PSA run f over ntasks, where f receives an AbstractArray/range of linear indices
julia
@inline function _maptasks(f::F, taskrange, threaded::_True)::Vector where F
+ ntasks = length(taskrange)
Customize this as needed. More tasks have more overhead, but better load balancing
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
This file mainly defines the applyreduce function.
This performs apply, but then reduces the result after flattening instead of rebuilding the geometry.
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.
centroid, area and distance have been implemented using the applyreduce framework.
julia
"""
+ 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
+
+### `_mapreducetasks` - flexible, threaded mapreduce
+
+import Base.Threads: nthreads, @threads, @spawn
Threading utility, modified Mason Protters threading PSA run f over ntasks, where f receives an AbstractArray/range of linear indices
WARNING: this will not work for mean/median - only ops where grouping is possible. That's because the implementation operates in chunks, and not globally.
If you absolutely need a single chunk, then threaded = false will always decompose to straight mapreduce without grouping.
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
This file defines common keyword documentation, that can be spliced into docstrings.
julia
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
+"""
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.
"""
+ 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)
Try to flatten over iterables
julia
function _flatten(f, ::Type{Target}, ::Nothing, iterable) where Target
+ if Tables.istable(iterable)
+ column = Tables.getcolumn(iterable, first(GI.geometrycolumns(iterable)))
+ Iterators.map(x -> _flatten(f, Target, x), column) |> Iterators.flatten
+ else
+ Iterators.map(x -> _flatten(f, Target, x), iterable) |> Iterators.flatten
+ end
+end
Flatten feature collections
julia
function _flatten(f, ::Type{Target}, ::GI.FeatureCollectionTrait, fc) where Target
+ Iterators.map(GI.getfeature(fc)) do feature
+ _flatten(f, Target, feature)
+ end |> Iterators.flatten
+end
+_flatten(f, ::Type{Target}, ::GI.FeatureTrait, feature) where Target =
+ _flatten(f, Target, GI.geometry(feature))
_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`.
+
+Usually 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"))
+
+"""
+ 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)
+ haveZ = (GI.is3d(child) for child in child_geoms)
+ haveM = (GI.ismeasured(child) for child in child_geoms)
+
+ consistentZ = length(child_geoms) == 1 ? true : all(==(first(haveZ)), haveZ)
+ consistentM = length(child_geoms) == 1 ? true : all(==(first(haveM)), haveM)
+
+ if !consistentZ || !consistentM
+ @show consistentZ consistentM
+ @show GI.is3d.(child_geoms)
+ @show GI.ismeasured.(child_geoms)
+ throw(ArgumentError("child geometries do not have consistent 3d or measure attributes."))
+ end
+
+ hasZ = first(haveZ)
+ hasM = first(haveM)
+
+ return T{hasZ,hasM}(child_geoms; crs, extent)
+end
A manifold is mathematically defined as a topological space that resembles Euclidean space locally.
In GeometryOps (and geodesy more generally), there are three manifolds we care about:
Planar: the 2d plane, a completely Euclidean manifold
Spherical: the unit sphere, but one where areas are multiplied by the radius of the Earth. This is not Euclidean globally, but all map projections attempt to represent the sphere on the Euclidean 2D plane to varying degrees of success.
Geodesic: the ellipsoid, the closest we can come to representing the Earth by a simple geometric shape. Parametrized by semimajor_axis and inv_flattening.
Generally, we aim to have Linear and Spherical be operable everywhere, whereas Geodesic will only apply in specific circumstances. Currently, those circumstances are area and segmentize, but this could be extended with time and https://github.com/JuliaGeo/SphericalGeodesics.jl.
julia
export Planar, Spherical, Geodesic
+export TraitTarget
+export BoolsAsTypes, _True, _False, _booltype
+
+"""
+ abstract type Manifold
+
+A manifold is mathematically defined as a topological space that resembles Euclidean space locally.
+
+We use the manifold definition to define the space in which an operation should be performed, or where a geometry lies.
+
+Currently we have `Planar`, `Spherical`, and `Geodesic` manifolds.
+"""
+abstract type Manifold end
+
+"""
+ Planar()
+
+A planar manifold refers to the 2D Euclidean plane.
+
+Z coordinates may be accepted but will not influence geometry calculations, which
+are done purely on 2D geometry. This is the standard "2.5D" model used by e.g. GEOS.
+"""
+struct Planar <: Manifold
+end
+
+"""
+ Spherical(; radius)
+
+A spherical manifold means that the geometry is on the 3-sphere (but is represented by 2-D longitude and latitude).
+
+By default, the radius is defined as the mean radius of the Earth, `6371008.8 m`.
+
+# Extended help
+
+!!! note
+ The traditional definition of spherical coordinates in physics and mathematics,
+ ``r, \\theta, \\phi``, uses the _colatitude_, that measures angular displacement from the `z`-axis.
+
+ Here, we use the geographic definition of longitude and latitude, meaning
+ that `lon` is longitude between -180 and 180, and `lat` is latitude between
+ `-90` (south pole) and `90` (north pole).
+"""
+Base.@kwdef struct Spherical{T} <: Manifold
+ radius::T = 6371008.8
+end
+
+"""
+ Geodesic(; semimajor_axis, inv_flattening)
+
+A geodesic manifold means that the geometry is on a 3-dimensional ellipsoid, parameterized by `semimajor_axis` (``a`` in mathematical parlance)
+and `inv_flattening` (``1/f``).
+
+Usually, this is only relevant for area and segmentization calculations. It becomes more relevant as one grows closer to the poles (or equator).
+"""
+Base.@kwdef struct Geodesic{T} <: Manifold
+ semimajor_axis::T = 6378137.0
+ inv_flattening::T = 298.257223563
+end
This struct holds a trait parameter or a union of trait parameters. It's essentially a way to construct unions.
julia
"""
+ 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)...}}()
+
+
+Base.in(::Trait, ::TraitTarget{Target}) where {Trait <: GI.AbstractTrait, Target} = Trait <: Target
In apply and applyreduce, 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.
TODO: should we switch to Static.jl?
julia
"""
+ abstract type BoolsAsTypes
+
+"""
+abstract type BoolsAsTypes end
+
+"""
+ struct _True <: BoolsAsTypes
+
+A struct that means `true`.
+"""
+struct _True <: BoolsAsTypes end
+
+"""
+ struct _False <: BoolsAsTypes
+
+A struct that means `false`.
+"""
+struct _False <: BoolsAsTypes end
+
+"""
+ _booltype(x)
+
+Returns a `BoolsAsTypes` from `x`, whether it's a boolean or a BoolsAsTypes.
+"""
+function _booltype end
+
+@inline _booltype(x::Bool)::BoolsAsTypes = x ? _True() : _False()
+@inline _booltype(x::BoolsAsTypes)::BoolsAsTypes = x
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 requirement 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 reference system, as a GeoFormatTypes.jl object or a string.
+- `target_crs`: the target coordinate reference 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 retrievable 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 `Geodesic` 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 = Planar()], 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::Manifold = Planar()`: The method to use for segmentizing the geometry. At the moment, only `Planar` (assumes a flat plane) and `Geodesic` (assumes geometry on the ellipsoidal Earth and uses Vincenty's formulae) are available.
+- `geom`: The geometry to segmentize. Must be a `LineString`, `LinearRing`, `Polygon`, `MultiPolygon`, or `GeometryCollection`, or some vector or table of those.
+- `max_distance::Real`: The maximum distance between vertices in the geometry. **Beware: for `Planar`, this is in the units of the geometry, but for `Geodesic` and `Spherical` it's in units of the radius of the sphere.**
+
+Returns a geometry of similar type to the input geometry, but resampled.
+"""
+function segmentize(geom; max_distance, threaded::Union{Bool, BoolsAsTypes} = _False())
+ return segmentize(Planar(), geom; max_distance, threaded = _booltype(threaded))
+end
This file holds implementations for the RadialDistance, Douglas-Peucker, and Visvalingam-Whyatt algorithms for simplifying geometries (specifically for polygons and lines).
The GEOS extension also allows for GEOS's topology preserving simplification as well as Douglas-Peucker simplification implemented in GEOS. Call this by passing GEOS(; method = :TopologyPreserve) or GEOS(; method = :DouglasPeucker) to the algorithm.
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 decreasing 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 unnecessary 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 connecting 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 unnecessary 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
This file defines some fundamental types used in GeometryOps.
Warning
Unlike in other Julia packages, only some types are defined in this file, not all. This is because we define types in the files where they are used, to make it easier to understand the code.
GEOS is a struct which instructs the method it's passed to as an algorithm to use the appropriate GEOS function via LibGEOS.jl for the operation.
It's generally a lot slower than the native Julia implementations, but it's useful for two reasons:
Functionality which doesn't exist in GeometryOps can be accessed through the GeometryOps API, but use GEOS in the backend until someone implements a native Julia version.
It's a good way to test the correctness of the native implementations.
julia
"""
+ GEOS(; params...)
+
+A struct which instructs the method it's passed to as an algorithm
+to use the appropriate GEOS function via `LibGEOS.jl` for the operation.
+
+Dispatch is generally carried out using the names of the keyword arguments.
+For example, `segmentize` will only accept a `GEOS` struct with only a
+`max_distance` keyword, and no other.
+
+It's generally a lot slower than the native Julia implementations, since
+it must convert to the LibGEOS implementation and back - so be warned!
+"""
+struct GEOS
+ params::NamedTuple
+end
+
+function GEOS(; params...)
+ nt = NamedTuple(params)
+ return GEOS(nt)
+end
These are definitions for convenience, so we don't have to type out alg.params every time.
julia
Base.get(alg::GEOS, key, value) = Base.get(alg.params, key, value)
+Base.get(f::Function, alg::GEOS, key) = Base.get(f, alg.params, key)
+
+"""
+ enforce(alg::GO.GEOS, kw::Symbol, f)
+
+Enforce the presence of a keyword argument in a `GEOS` algorithm, and return `alg.params[kw]`.
+
+Throws an error if the key is not present, and mentions `f` in the error message (since there isn't
+a good way to get the name of the function that called this method).
+"""
+function enforce(alg::GEOS, kw::Symbol, f)
+ if haskey(alg.params, kw)
+ return alg.params[kw]
+ else
+ error("$(f) requires a `$(kw)` keyword argument to the `GEOS` algorithm, which was not provided.")
+ end
+end
# Geospatial packages from Julia
+import GeoInterface as GI
+import GeometryOps as GO
+import GeoFormatTypes as GFT
+using GeoJSON # to load some data
+# Packages for coordinate transformation and projection
+import CoordinateTransformations
+import Proj
+# Plotting
+using CairoMakie
+using GeoMakie
We can also create a single LinearRing trait, the building block of a polygon. A LinearRing is simply a LineString with the same beginning and endpoint, i.e., an arbitrary closed shape composed of point pairs.
Now, we can use GeometryOps and CoordinateTransformations to shift polygon1 up, to avoid plotting over our earlier results. This is done through the GeometryOps.transform function.
Polygons can contain "holes". The first LinearRing in a polygon is the exterior, and all subsequent LinearRings are treated as holes in the leading LinearRing.
GeoInterface offers the GI.getexterior(poly) and GI.gethole(poly) methods to get the exterior ring and an iterable of holes, respectively.
Great, now we can make Points, MultiPoints, Lines, LineStrings, Polygons (with holes), and MultiPolygons and modify them using [CoordinateTransformations] and [GeometryOps].
Plot geometries on a map using GeoMakie and coordinate reference system (CRS)
In geospatial sciences we often have data in one Coordinate Reference System (CRS) (source) and would like to display it in different (destination) CRS. GeoMakie allows us to do this by automatically projecting from source to destination CRS.
Here, our source CRS is common geographic (i.e. coordinates of latitude and longitude), WGS84.
julia
source_crs1 = GFT.EPSG(4326)
GeoFormatTypes.EPSG{1}((4326,))
Now let's pick a destination CRS for displaying our map. Here we'll pick natearth2.
julia
destination_crs = "+proj=natearth2"
"+proj=natearth2"
Let's add land area for context. First, download and open the Natural Earth global land polygons at 110 m resolution.GeoMakie ships with this particular dataset, so we will access it from there.
Natural Earth has lots of other datasets, and there is a Julia package that provides an interface to it called NaturalEarth.jl.
Read the land MultiPolygons as a GeoJSON.FeatureCollection.
julia
land_geo = GeoJSON.read(land_path)
FeatureCollection with 127 Features
We then need to create a figure with a GeoAxis that can handle the projection between source and destination CRS. For GeoMakie, source is the CRS of the input and dest is the CRS you want to visualize in.
Create geospatial geometries with embedded coordinate reference system information
Great, we can make geometries and plot them on a map... now let's export the data to common geospatial data formats. To do this we now need to create geometries with embedded CRS information, making it a geospatial geometry. All that's needed is to include ; crs = crs as a keyword argument when constructing the geometry.
Let's do this for a new Polygon
julia
r = 3;
+k = 7;
+ϴ = 0:0.01:2pi;
+x = r .* (k + 1) .* cos.(ϴ) .- r .* cos.((k + 1) .* ϴ);
+y = r .* (k + 1) .* sin.(ϴ) .- r .* sin.((k + 1) .* ϴ);
+ring4 = GI.LinearRing(Point.(zip(x, y)))
It is good practice to only include CRS information with the highest-level geometry. Not doing so can bloat the memory footprint of the geometry. CRS information can be included at the individual Point level but is discouraged.
And let's create second Polygon by shifting the first using CoordinateTransformations
Typically, you'll also want to include attributes with your geometries. Attributes are simply data that are attributed to each geometry. The easiest way to do this is to create a table with a :geometry column. Let's do this using DataFrames.
julia
using DataFrames
+df = DataFrame(geometry=[geopoly1, geopoly2])
Now let's add a couple of attributes to the geometries. We do this using DataFrames' ! mutation syntax that allows you to add a new column to an existing data frame.
There are Julia packages for most commonly used geographic data formats. Below, we show how to export that data to each of these.
We begin with GeoJSON, which is a JSON format for geospatial feature collections. It's human-readable and widely supported by most web-based and desktop geospatial libraries.
Now, let's save as a Shapefile. Shapefiles are actually a set of files (usually 4) that hold geometry information, a CRS, and additional attribute information as a separate table. When you give Shapefile.write a file name, it will write 4 files of the same name but with different extensions.
Now, let's save as a GeoParquet. GeoParquet is a geospatial extension to the Parquet format, which is a high-performance data store. It's great for storing large amounts of data in a single file.
Finally, if there's no Julia-native package that can write data to your desired format (e.g. .gpkg, .gml, etc), you can use GeoDataFrames. This package uses the GDAL library under the hood which supports writing to nearly all geospatial formats.
And there we go, you can now create mapped geometries from scratch, manipulate them, plot them on a map, and save them in multiple geospatial data formats.
+
+
+
+
\ No newline at end of file
diff --git a/previews/PR239/tutorials/geodesic_paths.html b/previews/PR239/tutorials/geodesic_paths.html
new file mode 100644
index 000000000..0ce357761
--- /dev/null
+++ b/previews/PR239/tutorials/geodesic_paths.html
@@ -0,0 +1,35 @@
+
+
+
+
+
+ Geodesic paths | GeometryOps.jl
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
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, for any kind of table join operation:
julia
using FlexiJoins
+innerjoin((table1, table1),
+ by_pred(:table1_column, predicate_function, :table2_column) # & add other conditions here
+)
+leftjoin((table1, table1),
+ by_pred(:table1_column, predicate_function, :table2_column) # & add other conditions here
+)
+rightjoin((table1, table1),
+ by_pred(:table1_column, predicate_function, :table2_column) # & add other conditions here
+)
+outerjoin((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}'),n={name:"index.md"};function s(r,e,l,c,d,h){return i(),a("div",null,e[0]||(e[0]=[o('
