GeoGrids.jl

Appearance

GeoGrids API ​

Public ​

GeoGrids.BoxBorder Type
julia
BoxBorder{P} <: BorderGeometry{P}

Struct representing a Box in both LatLon and Cartesian coordinates.

Fields:

  • latlon::BOX_LATLON{P}: The borders in LatLon CRS
  • cart::BOX_CART{P}: The borders in Cartesian2D CRS

Where P is the machine type (e.g., Float32, Float64) for the coordinates.

source

GeoGrids.ClippedRegion Type
julia
ClippedRegion{P} <: AbstractRegion

Type representing a region which is defined as the intersection (obtained by Sutherland-Hodgman clipping algorithm) of an arbitrary region and a mask.

Fields:

  • name::String: Name of the region
  • original::AbstractRegion: Original input before clipping
  • mask::Union{BoxBorder{P}, PolyBorder{P}}: Mask used for clipping the region
  • domain::MultiBorder{P}: Domain of the region

Where P is the precision type for coordinates.

This can be useful to easily defin regions which are obtained by e.g. specific countries or continent cut by simple geometries like boxes or other polygons.

Constructor

ClippedRegion(original, mask::Union{BoxBorder{P}, PolyBorder{P}}; name::String)

The constructor takes an arbitrary region and a mask and creates a ClippedRegion by clipping the region with the mask using the Sutherland-Hodgman algorithm.

source

GeoGrids.EO Type
julia
EO

Struct used to create function methods that return more than one output. Used within multiple methods of the GeoGrids API, usually given as last optional argument.

source

GeoGrids.GeoRegion Type
julia
GeoRegion{D,P} <: AbstractRegion

Type representing a geographical region based on CountriesBorders.

Fields:

  • name::String: Name of the region
  • continent::String: Continent of the region
  • subregion::String: Subregion within the continent
  • admin::String: Administrative area
  • domain::D: Domain of the region
  • convexhull::PolyBorder{P}: Convex hull of the region

Where D is the domain type and P is the precision type for coordinates.

source

GeoGrids.GeoRegionOffset Type
julia
GeoRegionOffset{D,P} <: AbstractRegion

Type representing an enlarged geographical region based on a GeoRegion.

Fields:

  • original::GeoRegion{D,P}: The original GeoRegion
  • name::String: Name of the enlarged region
  • domain::MultiBorder{P}: Domain of the enlarged region
  • convexhull::PolyBorder{P}: Convex hull of the enlarged region

Constructors

GeoRegionOffset(; name="offset_georegion", continent="", subregion="", admin="", delta::Number, resolution=110, refRadius=constants.Re_mean, magnitude=3, precision=7)
GeoRegionOffset(gr::GeoRegion, delta::Number; name="offset_georegion", refRadius=constants.Re_mean, magnitude=3, precision=7)

Create an enlarged GeoRegion either from scratch or from an existing GeoRegion.

Arguments

  • delta: Distance to enlarge the region by, in meters
  • gr::GeoRegion: The original GeoRegion to enlarge (for the second constructor)

Keyword Arguments

  • name::String="enlarged_region": Name of the enlarged region
  • continent::String="": Continent of the region (only for the first constructor)
  • subregion::String="": Subregion within the continent (only for the first constructor)
  • admin::String="": Administrative area (only for the first constructor)
  • resolution::Int=110: Resolution of the geographical data (only for the first constructor)
  • refRadius::Float64=constants.Re_mean: Reference radius of the Earth
  • magnitude::Int=3: Magnitude for polygon offsetting
  • precision::Int=7: Precision for polygon offsetting

Returns

  • GeoRegionOffset: The enlarged geographical region

source

GeoGrids.GlobalRegion Type
julia
GlobalRegion <: AbstractRegion

Type representing a global region.

source

GeoGrids.GreatCircleMetric Type
julia
GreatCircleMetric(radius=6_371_000)

The great circle distance between two points on a sphere of given radius. This is basically equivalent to Haversine from Distances.jl but allows computing distance between points already expressed in LatLon or Point{🌐, <:LatLon} types.

source

GeoGrids.H3 Type
julia
H3 <: AbstractTiling

Struct representing an H3 tiling.

source

GeoGrids.HEX Type
julia
HEX <: AbstractTiling

Struct representing a hexagonal tiling.

Fields:

  • direction::Symbol: Default direction of hexagons in the tiling (:pointy or :flat)
  • pattern::Symbol: Default pattern shape to be used with this type of tiling (:circ or :hex)

source

GeoGrids.HotSpotRegion Type
julia
HotSpotRegion{P} <: AbstractRegion

Type representing a hot spot region, which is defined as the set of points which are less than radius distance from a given center in LatLon CRS.

Fields:

  • name::String: Name identifying the hot spot
  • center::POINT_LATLON{P}: Center of the hot spot
  • radius::Float64: Radius of the hot spot [m]
  • domain::PolyBorder{P}: Polygon identifying the polygon in latlon which represents a circle of specified radius from the center

Constructor

HotSpotRegion(; name::String, center::Union{LATLON, POINT_LATLON}, radius::Number)

Create a HotSpotRegion from a name, a center and a radius.

source

GeoGrids.ICO Type
julia
ICO <: AbstractTiling

Struct representing an icosahedral tiling.

Fields:

  • correction::Number: Default correction factor for the icosahedral cell grid partial overlap
  • pattern::Symbol: Default pattern shape to be used with this type of tiling (:circ or :hex)

source

GeoGrids.LatBeltRegion Type
julia
LatBeltRegion <: AbstractRegion

Type representing a latitude belt region.

Fields:

  • name::String: Name of the region
  • lim::Tuple{ValidAngle,ValidAngle}: Latitude limits of the belt in degrees

source

GeoGrids.LatLonTree Type
julia
LatLonTree{T <: NNTree, P <: Union{LatLon, Point{🌐, <:LatLon}}}

Structure providing a modified NNTree from NearestNeighbors.jl that allows querying with Points in LatLon coordinates.

The LatLonTree internally stores an NNTree where the provided points are converted to SVector{2, Float64} and store the longitude and latitude values of the provided points in radians.

Constructors

LatLonTree{BallTree}(points::AbstractVector, metric::Metric = GreatCircleMetric(first(points)); kwargs...)
LatLonTree{KDTree}(points::AbstractVector, metric::Metric = Euclidean(); kwargs...)
LatLonTree(points::AbstractVector; kwargs...)

The first two constructors explicitly specify the type of NNTree to use internally, and allow customizing the metric used while the latter method simply fall backs to the BallTree with default metric.

The default preferred tree structure is the BallTree one as it computes distance between points using the Great Circle distance assuming spherical earth, which is a good approximation for actual distances between points on the surface of the earth (and much faster than the actual inverse geodesic computation)

Instances of LatLonTree support the following functions from NearestNeighbors.jl:

  • knn
  • knn!
  • inrangecount
  • inrange
  • inrange!

All these methods allow specifing the query points as one of the following:

  • A LatLon coordinate
  • A Point{🌐, <:LatLon} point
  • A vector with either of the two previous types as eltype

The inrangecount, inrange and inrange! methods are only callable with instances of LatLonTree{<:BallTree} as the distance with KDTree is not really meaningful.

source

GeoGrids.MultiBorder Type
julia
MultiBorder{P} <: BorderGeometry{P}

Struct representing a Multi in both LatLon and Cartesian coordinates.

Fields:

  • latlon::MULTI_LATLON{P}: The borders in LatLon CRS
  • cart::MULTI_CART{P}: The borders in Cartesian2D CRS

Where P is the precision type (e.g., Float32, Float64) for the coordinates.

source

GeoGrids.MultiRegion Type
julia
MultiRegion{P} <: AbstractRegion

Type representing a region which is defined as the union of multiple PolyAreas.

Fields:

  • name::String: Name identifying the multi region
  • domain::MultiBorder{P}: MultiPolygon identifying the various regions included in the multi region

Constructor

MultiRegion(areas::Vector; name::String)

The constructor takes a vector of polyareas, Multi, or other AbstractRegions and creates a single MultiBorder which encompasses all the polyareas of the provided areas.

source

GeoGrids.PolyBorder Type
julia
PolyBorder{P} <: BorderGeometry{P}

Struct representing a PolyArea in both LatLon and Cartesian coordinates.

Fields:

  • latlon::POLY_LATLON{P}: The borders in LatLon CRS
  • cart::POLY_CART{P}: The borders in Cartesian2D CRS

Where P is the machine type (e.g., Float32, Float64) for the coordinates.

source

GeoGrids.PolyRegion Type
julia
PolyRegion{P} <: AbstractRegion

Type representing a polygonal region based on PolyArea.

Fields:

  • name::String: Name of the region
  • domain::PolyBorder{P}: Domain of the region as a PolyBorder

Where P is the precision type for coordinates.

source

GeoGrids.PolyRegionOffset Type
julia
PolyRegionOffset{P} <: AbstractRegion

Struct representing an enlarged polygonal region.

Fields:

  • original::PolyRegion{P}: The original PolyRegion
  • name::String: Name of the enlarged region
  • domain::MultiBorder{P}: Domain of the enlarged region as a MultiBorder

Constructors

PolyRegionOffset(delta::Number; kwargs...)
PolyRegionOffset(pr::PolyRegion, delta::Number; kwargs...)

Create an enlarged PolyRegion either from scratch or from an existing PolyRegion.

Arguments

  • deltaDist: Distance to enlarge the region by, in meters
  • pr::PolyRegion: The original PolyRegion to enlarge (for the second constructor)

Keyword Arguments

  • name::String="offset_polyregion": Name of the enlarged region
  • domain: Domain of the region (only for the first constructor)
  • refRadius::Float64=constants.Re_mean: Reference radius of the Earth
  • magnitude::Int=3: Magnitude for polygon offsetting
  • precision::Int=7: Precision for polygon offsetting

Returns

  • PolyRegionOffset: The enlarged polygonal region

source

GeoGrids.color_greedy Method
julia
color_greedy(points::AbstractVector{<:Union{LatLon,Point{🌐,<:LatLon{WGS84Latest}}}}, radius::Number, count::Int; cutoff_dist::Number=radius * 10.0, min_dist::Number=radius * 2)

Color a set of points with n colors with an extended greedy algorithm. The algorithm makes sure no points closer than min_dist share the same color. Additionally, it tries to optimize the total spatial distribution of colors.

Arguments

  • points: A vector of points.
  • radius: The radius of the individual cells.
  • count: The number of colors to use.
  • cutoff_dist: The cutoff distance for the greedy algorithm. A low value will result in a faster but less optimal coloring.
  • min_dist: The minimum distance for the greedy algorithm. If the minimum distance between two colors is not met, the coloring will fail.

Returns

  • A vector of integers where each entry represents the "color" of the cell with the same index.

source

GeoGrids.filter_points Method
julia
filter_points(points::AbstractVector{<:LatLon}, domain::Union{GeoRegion, PolyRegion, LatBeltRegion, GeoRegionOffset, PolyRegionOffset}) -> Vector{Input Type}

Filters a list of points based on whether they fall within a specified geographical domain.

Arguments

  • points: An array of points. The points are LatLon.
  • domain: A geographical domain which can be of type GeoRegion or PolyRegion, LatBeltRegion, GeoRegionOffset, or PolyRegionOffset in alternative a Meshes.Domain of type GeometrySet or PolyArea.
  • ::EO: An EO object for additional output containing the indices of the filtered points (wrt the input).

Returns

  • A vector of points that fall within the specified domain, subsection of the input vector. The output is of the same type as the input.

source

GeoGrids.gen_circle_pattern Method
julia
gen_circle_pattern(centers::AbstractVector{Point{🌐,<:LatLon{WGS84Latest}}}, radius::Number; refRadius::Number=constants.Re_mean, n::Int=20) -> Vector{Vector{Point{🌐,<:LatLon{WGS84Latest}}}
gen_circle_pattern(c::Point{🌐,<:LatLon{WGS84Latest}}, radius::Number; kwargs...) -> Vector{Point{🌐,<:LatLon{WGS84Latest}}
gen_circle_pattern(centers::AbstractVector{<:LatLon}, radius::Number; kwargs...) -> Vector{Vector{Point{🌐,<:LatLon{WGS84Latest}}}
gen_circle_pattern(c::LatLon, radius::Number; kwargs...) -> Vector{Point{🌐,<:LatLon{WGS84Latest}}

The gen_circle_pattern function generates circles of geographical points centered at each point in the centers vector. The points are generated on the Earth's surface using a spherical approximation, where latitude and longitude are converted to spherical coordinates (theta-phi), and then an angular offset is applied to generate the circle. The single point versions of the function (gen_circle_pattern(c::Point{🌐,<:LatLon{WGS84Latest}}, radius::Number; kwargs...) and gen_circle_pattern(c::LatLon, radius::Number; kwargs...)) are convenience methods that allow you to generate a circle pattern around a single center point. Tis function is used to create a plottable patter od the circles around a center point.

Arguments

  • centers::AbstractVector{Point{🌐,<:LatLon{WGS84Latest}}}: A vector of geographical points in the WGS84 coordinate system. Each point represents the center of a circle.
  • radius::Number: The radius of the circles to generate, in the same units as the reference radius (refRadius).
  • refRadius::Number=constants.Re_mean: The reference radius for the spherical approximation, defaulting to the mean Earth radius (Re_mean).
  • n::Int=20: The number of points to generate along each circle's circumference.

Keyword Arguments

  • kwargs...: Additional keyword arguments passed to other variations of the function.

Returns

  • Vector{Vector{Point{🌐,<:LatLon{WGS84Latest}}}}: A vector where each element is a vector of LatLon points representing a circle.

source

GeoGrids.gen_hex_lattice Function
julia
gen_hex_lattice(spacing, direction = :pointy; kwargs...)

Generate a hexagonal lattice of points with equal distance spacing between neighboring points.

The generated hexagonal lattice will have distance between points on the same row/column that will depend on the second argument direction:

If direction = :pointy, neighboring points on the same row (points which have the same y coordinate) will be at a distance spacing from one another, while points on the same column (sharing the x coordinate) will have a distance equivalent to √3 * spacing.

If direction = :flat, the distance will be reversed, so points on the same column will have a distance equivalent to spacing while points on the same row will have a distance equivalent to √3 * spacing.

Arguments

  • spacing: spacing between neighboring points
  • direction: specifies the direction of minimum distance between neighboringpoints. Defaults to :pointy.

See also: _gen_regular_lattice

source

GeoGrids.gen_hex_pattern Method
julia
gen_hex_pattern(filtered::AbstractVector{Point{🌐,<:LatLon{WGS84Latest}}}, idxs::AbstractVector{<:Number}, mesh::SimpleMesh) -> Vector{Vector{LatLon}}
gen_hex_pattern(p::Point{🌐,<:LatLon{WGS84Latest}}, idx::Number, mesh::SimpleMesh) -> Vector{LatLon}
gen_hex_pattern(filtered::AbstractVector{<:LatLon}, idxs::AbstractVector{<:Number}, mesh::SimpleMesh) -> Vector{Vector{LatLon}}
gen_hex_pattern(p::LatLon, idx::Number, mesh::SimpleMesh) -> Vector{LatLon}

The gen_hex_pattern function generates patterns of hexagons (or other polygons) around a set of geographical points using a provided mesh. The mesh is expected to contain polygons that are indexed by the idxs argument, and each polygon is converted into a set of geographical points in latitude and longitude. The function iterates over each polygon in the mesh corresponding to the indices in idxs, converting the vertices of the polygon into LatLon points that represent the corners of the hexagon (or other polygon) around the corresponding center point. The single point versions of the function (gen_hex_pattern(p::Point{🌐,<:LatLon{WGS84Latest}}, idx::Number, mesh::SimpleMesh) and gen_hex_pattern(p::LatLon, idx::Number, mesh::SimpleMesh)) are convenience methods that allow you to generate a pattern around a single center point.

Arguments

  • filtered::AbstractVector{Point{🌐,<:LatLon{WGS84Latest}}}: A vector of geographical points in the WGS84 coordinate system that represent the centers of the hexagons or polygons.
  • idxs::AbstractVector{<:Number}: A vector of indices corresponding to the polygons within the mesh.
  • mesh::SimpleMesh: A mesh object containing the polygons (typically hexagons) used to generate the patterns.

Keyword Arguments

  • kwargs...: Additional keyword arguments passed to other variations of the function.

Returns

  • Vector{Vector{<:POINT_LATLON}}: A vector where each element is a vector of LatLon points representing the vertices of the polygons (typically hexagons) for each center point.

source

GeoGrids.generate_tesselation Method
julia
generate_tesselation(region::Union{GeoRegion, PolyRegion, GeoRegionOffset, PolyRegionOffset}, radius::Number, type::HEX; refRadius::Number=constants.Re_mean, kwargs_lattice...) -> AbstractVector{<:Point{🌐,<:LatLon{WGS84Latest}}}
generate_tesselation(region::Union{GeoRegion, PolyRegion, GeoRegionOffset, PolyRegionOffset}, radius::Number, type::HEX, ::EO; refRadius::Number=constants.Re_mean, kwargs_lattice...) -> AbstractVector{<:Point{🌐,<:LatLon{WGS84Latest}}}, AbstractVector{<:AbstractVector{<:Point{🌐,<:LatLon{WGS84Latest}}}}

The generate_tesselation function generates a hexagonal cell layout for a given geographical region. It calculates the cell grid layout centered around the centroid of the main area of the region and returns the points within the specified region. A method for using hexagonal tesselation for GlobalRegion and LatBeltRegion is not provided because of the large size of surface to be covered, the local hexagonal tasellation would be inaccurate.

Arguments

  • region::Union{GeoRegion, PolyRegion}: The geographical region for which the

cell layout is generated. Larger regions like global and LatBeltRegions are not supported because of the problem of regular tassellation of the sphere.

  • radius::Number: The radius of each hexagonal cell. Has to be intended as the circumscribed circumference.
  • type::HEX: A parameter indicating the type of lattice (only HEX is supported).
  • refRadius::Number: The radius of the Earth in meters (default is constants.Re_mean).
  • ::EO: an extra parameter enabling a Vector{Ngon} the contours of each cell. The mesh originating these contours is obtained using VoronoiTesselation.
  • kwargs_lattice...: Additional keyword arguments passed to the gen_hex_lattice function.

Returns

  • Vector{Point{🌐,<:LatLon{WGS84Latest}}}: A Vecotr of points (LatLon) representing the cell centers within the specified region.

See also: gen_hex_lattice, _generate_tesselation, _hex_tesselation_centroids, _tesselate, HEX, GeoRegion, PolyRegion

source

GeoGrids.generate_tesselation Method
julia
generate_tesselation(region::GlobalRegion, radius::Number, type::ICO; refRadius::Number=constants.Re_mean) -> AbstractVector{<:LatLon}
generate_tesselation(region::GlobalRegion, radius::Number, type::ICO, ::EO; refRadius::Number=constants.Re_mean) -> AbstractVector{<:LatLon}, AbstractVector{<:AbstractVector{<:LatLon}}
generate_tesselation(region::Union{LatBeltRegion, GeoRegion, PolyRegion, GeoRegionOffset, PolyRegionOffset}, radius::Number, type::ICO; refRadius::Number=constants.Re_mean) -> AbstractVector{<:LatLon}
generate_tesselation(region::Union{LatBeltRegion, GeoRegion, PolyRegion, GeoRegionOffset, PolyRegionOffset}, radius::Number, type::ICO, ::EO; refRadius::Number=constants.Re_mean) -> AbstractVector{<:LatLon}, AbstractVector{<:AbstractVector{<:LatLon}}

The generate_tesselation function generates a cell layout using an icosahedral grid for a given geographical region. The function adapts the grid based on the specified radius and applies a correction factor (see _adapted_icogrid). The radius as to be intended as the semparation angle of the point on the icosahedral grid. It then filters the grid points to include only those within the specified region.

Arguments

  • region::Union{LatBeltRegion, GeoRegion, PolyRegion}: The geographical region for which the cell layout is generated. This can be a LatBeltRegion, GeoRegion, or PolyRegion.
  • radius::Number: The radius used to adapt the icosahedral grid.
  • type::ICO: An object specifying the type of icosahedral grid and its correction factor.
  • ::EO: an extra parameter enabling a Vector{Ngon} the contours of each cell. The mesh originating these contours is obtained using VoronoiTesselation.
  • refRadius::Number: The radius of the Earth in meters (default is constants.Re_mean).
  • maxPrec=10^7: The maximum precision for the grid generation. It controls the maximum number of points in the grid and can be adjusted based on the application's requirements. It should be increased when incredibly small cells (approximately below 5 km radius, consider 10 km radius is the lowerbound for 3GPP NTN, see TR38.821) are needed.

Returns

  • Vector{Point{🌐,<:LatLon{WGS84Latest}}}: A Vecotr of points (LatLon) representing the cell centers within the specified region.

See also: _adapted_icogrid(), icogrid(), filter_points(), GeoRegion, LatBeltRegion, PolyRegion, GlobalRegion, ICO

source

GeoGrids.icogrid Method
julia
icogrid(; N::Union{Int,Nothing}=nothing, sepAng::Union{ValidAngle,Nothing}=nothing, 
        maxPrec=10^7, spheRadius=1.0, pointsToCheck::Int=100, tol=10)

Generates a grid of points on the surface of a sphere based on an icosahedral subdivision.

Arguments

  • N::Union{Int,Nothing}: The subdivision level of the icosahedron. Higher values result in a finer grid. If provided, sepAng must be nothing.
  • sepAng::Union{ValidAngle,Nothing}: The desired angular separation between points on the grid. Must be a positive angle (in radians or degrees). If provided, N must be nothing.
  • maxPrec::Int=10^7: The maximum allowed number of points for a given sepAng. It has to be intended as a precision limit for the point computation, see: _points_required_for_separation_angle.
  • spheRadius::Float64=1.0: The radius of the sphere on which the grid is generated.
  • pointsToCheck::Int=100: The number of points to check when calculating the required subdivision level for a given sepAng, see: _points_required_for_separation_angle.
  • tol::Int=10: The tolerance level for precision when determining the required subdivision level, see: _points_required_for_separation_angle.

Returns

  • A vector of points on the sphere, represented as LatLon{WGS84Latest} objects, converted to degrees.

Notes

  • If both N and sepAng are provided, an error is raised. Only one of these arguments should be specified.
  • If sepAng is negative, it will be converted to a positive value with a warning.
  • The sepAng input must satisfy -360Β° ≀ x ≀ 360Β° if provided as a number. Use Β° or rad from the Unitful package to specify angles in degrees or radians.

source

GeoGrids.offset_region Method
julia
offset_region(originalRegion::GeoRegion, deltaDist; refRadius=constants.Re_mean, magnitude=3, precision=7)
offset_region(originalRegion::PolyRegion, deltaDist; refRadius=constants.Re_mean, magnitude=3, precision=7)

Offset a GeoRegion or PolyRegion by a given distance. This function offsets each polygon in the region separately and combines the results into a Multi geometry.

Arguments

  • originalRegion::Union{GeoRegion,PolyRegion}: The original region to be offset.
  • deltaDist: The distance to offset the region by, in meters. Positive for enlargement, negative for shrinking.
  • refRadius::Float64=constants.Re_mean: The reference radius to use for the Earth.
  • magnitude::Int=3: The number of integer digits for IntPoint conversion.
  • precision::Int=7: The total number of digits to be considered for each coordinate in IntPoint conversion.

Returns

  • Multi: A Multi geometry containing the offset polygons.

Notes

  • For GeoRegion, only the outer ring of each polygon is considered for offsetting.
  • For PolyRegion, if multiple outer rings are produced, inner rings are ignored and separate PolyAreas are created for each outer ring.

source

GeoGrids.rectgrid Method
julia
rectgrid(xRes::ValidAngle; yRes::ValidAngle=xRes) -> Array{Point{🌐,<:LatLon{WGS84Latest}}, 2}

Create a rectangular grid of latitude and longitude points with a specified grid resolutions. The function validates the input resolutions to ensure they are within the range of -180Β° to 180Β°. If a negative resolution is provided, it is converted to a positive value with a warning. The resolution values are used to create a rectangular grid covering the entire range of latitudes [-90Β°, 90Β°] and longitudes [-180Β°, 180Β°).

Arguments

  • xRes::ValidAngle: The resolution for the latitude grid spacing. This can be a real number (interpreted as degrees) or a ValidAngle.
  • yRes::ValidAngle: The resolution for the longitude grid spacing. This is optional and defaults to xRes if not provided. This can be a real number (interpreted as degrees) or a ValidAngle.

Returns

  • A 2D array of Point{🌐,<:LatLon{WGS84Latest}} objects representing the grid of latitude and longitude points.

source

GeoGrids.vecgrid Method
julia
vecgrid(gridRes::ValidAngle) -> Vector{Point{🌐,<:LatLon{WGS84Latest}}}

Generate a vector of latitude points from the equator to the North Pole with a specified resolution. The function validates the input resolution to ensure it is within the range of -90Β° to 90Β°. If a negative resolution is provided, it is converted to a positive value with a warning. The resolution value is then used to create a vector of latitude points ranging from 0Β° to 90Β° (the North Pole). Each latitude point is represented as a LatLon object with a fixed longitude of 0Β°.

Arguments

  • gridRes::ValidAngle: The resolution for the latitude grid spacing. This can be a real number (interpreted as degrees) or a ValidAngle.

Returns

  • A vector of Point{🌐,<:LatLon{WGS84Latest}} objects representing latitude points from the equator (0Β°) to the North Pole (90Β°) with the specified resolution.

source

Private ​

GeoGrids.BorderGeometry Type
julia
abstract type BorderGeometry{P} <: Geometry{🌐,LATLON{P}} end

Abstract type for all border geometries.

source

GeoGrids._adapted_icogrid Method
julia
_adapted_icogrid(radius::Number; correctionFactor=3/2)

The _adapted_icogrid function generates an icosahedral grid with a specified radius. It defines the separation angle for the icosahedral grid using a correction factor to adapt the cell centers' distances, ensuring the grid is appropriate for the desired scale.

Arguments

  • radius::Number: The radius used to define the separation angle for the icosahedral grid. This radius helps determine the distance between the grid points.

Keyword Arguments

  • correctionFactor=1.2: The correction factor used to adapt the cell centers' distances to ensure the grid is appropriate for the desired scale.
  • refRadius=constants.Re_mean: The reference radius for the spherical approximation, defaulting to the mean Earth radius (Re_mean).
  • maxPrec=10^7: The maximum precision for the grid generation. It controls the maximum number of points in the grid and can be adjusted based on the application's requirements, see: _points_required_for_separation_angle.
  • tol=10: The tolerance level for precision when determining the required subdivision level, see: _points_required_for_separation_angle.

Returns

  • grid: The generated icosahedral grid based on the calculated separation angle. The specific structure and format of the returned grid depend on the icogrid function being used.

source

GeoGrids._add_angular_offset Method
julia
_add_angular_offset(inputΞΈΟ•, offsetΞΈΟ•) -> NamedTuple{(:ΞΈ, :Ο•), Tuple{Float64, Float64}}

Add an angular offset to given spherical coordinates.

Arguments

  • inputΞΈΟ•::NamedTuple{(:ΞΈ, :Ο•), Tuple{Float64, Float64}}: The input spherical coordinates with components ΞΈ (polar angle) and Ο• (azimuthal angle) in radians.
  • offsetΞΈΟ•::NamedTuple{(:ΞΈ, :Ο•), Tuple{Float64, Float64}}: The offset spherical coordinates with components ΞΈ (polar angle) and Ο• (azimuthal angle) in radians.

Returns

  • NamedTuple{(:ΞΈ, :Ο•), Tuple{Float64, Float64}}: The new spherical coordinates after applying the angular offset, with components ΞΈ and Ο• in radians.

source

GeoGrids._fibonaccisphere_classic_partial Method
julia
_fibonaccisphere_classic_partial(N; spheRadius=1.0, pointsToCheck::Int=100)

Arguments:

  • N: an integer representing the number of points to generate on the surface of the sphere.
  • spheRadius: (optional) a float representing the radius of the sphere.
  • pointsToCheck: (optional) an integer representing the number of points to return starting from the first generated.

Output:

  • points: an array of 3D points on the surface of the sphere represented as SVector{3}.

source

GeoGrids._find_min_separation_angle Method
julia
_find_min_separation_angle(points)

This function takes an array of 3D Cartesian points as input and computes the smallest angle between any two points in the array. It does this by iterating over all unique pairs of points in the array and computing the angle between them using the angle``function. The smallest angle encountered during the iteration is stored in the variablesep` and returned as the output of the function.

Arguments:

  • points: an array of 3D points in the Cartesian plane represented as Tuples, Arrays, SVectors.

Output:

  • sep: the smallest angle between any two points in the input array, returned as Uniful.Quantity in degrees.

source

GeoGrids._gen_regular_lattice Method
julia
_gen_regular_lattice(dx::T, dy, ds; x0=zero(T), y0=zero(T), M::Int=100, N::Int=M) where {T}

The _gen_regular_lattice function generates a regular lattice of points in a two-dimensional space. The lattice is defined by its spacing in the x and y directions (dx and dy), an additional offset (ds), and optional starting positions (x0 and y0). The lattice spans 2M + 1 rows and 2N + 1 columns centered around the origin.

Arguments

  • dx::T: The spacing between points in the x direction.
  • dy::T: The spacing between points in the y direction.
  • ds::T: The additional offset in the x direction per row.
  • x0::T: The x-coordinate of the starting position. Default is zero(T).
  • y0::T: The y-coordinate of the starting position. Default is zero(T).
  • M::Int: The number of points in the x direction from the center. Default is 100.
  • N::Int: The number of points in the y direction from the center. Default is equal to M.

Returns

  • Array{SVector{2,T},2}: A 2D array of points represented as static vectors (SVector{2,T}) from the StaticArrays package. Each point is in the form (x, y).

source

GeoGrids._get_theta_phi Method
julia
_get_theta_phi(k::Number, N::Number) -> Tuple{Number, Number}

Calculate the spherical coordinates ΞΈ (theta) and Ο• (phi) for a given index k and total number of points N using the Golden Ratio method.

Arguments

  • k::Number: The index of the point for which the spherical coordinates are to be calculated. This should typically be an integer between 0 and N-1.
  • N::Number: The total number of points for which the spherical coordinates are to be calculated.

Returns

  • A tuple (ΞΈ, Ο•) where:
    • ΞΈ::Number: The longitude angle in rad, ranging from [0, 360].
    • Ο•::Number: The latitude angle in rad, ranging from [0, 180] from the North Pole.

source

GeoGrids._hex_tesselation_centroids Method
julia
_hex_tesselation_centroids(origin::Point{🌐,<:LatLon{WGS84Latest}}, radius::Number; direction::Symbol=:pointy, Re::Number=constants.Re_mean, kwargs_lattice...)

This function generates the centroids of a hexagonal tessellation on the Earth's surface, centered at the origin. The tessellation is created based on a given radius and direction. The function converts the offsets of the hexagonal grid to latitude and longitude coordinates.

Arguments

  • origin::Point{🌐,<:LatLon{WGS84Latest}}: The lat-lon coordinates of the center of the tessellation.
  • radius::Number: The radius of the hexagons in the tessellation in meters.
  • direction::Symbol: The direction of the hexagons, either :pointy (default) or :flat.
  • Re::Number: The mean radius of the Earth in meters (default is constants.Re_mean).
  • kwargs_lattice...: Additional keyword arguments for the hexagonal lattice generation.

Returns

  • Vector{Point{🌐,<:LatLon{WGS84Latest}}}: A vector of Point{🌐,<:LatLon{WGS84Latest}} objects representing the centroids of the hexagonal tessellation in latitude and longitude.

source

GeoGrids._icogrid Method
julia
_icogrid(N::Int)

This function generates N uniformly distributed points on the surface of a unitary sphere using the classic Fibonacci Spiral method as described in [1]. Contrary to the Ichosahedral grid generation process, with the Fibonacci Spiral method it is possible to generate a grid of points uniformly distributed in the area for a generic N value. As a drawback, the structure of the points do not follow a "perfect simmetry" however, the density of points in the area is preserved quasi-constant.

Arguments:

  • N::Int: The number of points to generate.
  • coord::Symbol: The type of coordinates of generated points (:sphe | :cart).
  • radius: the sphere radius in meters (unitary as default)

Output:

  • pointsVec: a Vector{SVector} of the generated points. Each element corresponds to a point on the surface of the sphere, the SVector contains either the x, y, and z (:cart) or lat, lon (:sphe) (LAT=x, LON=y) in rad coordinates of the point.

References

  1. http://extremelearning.com.au/how-to-evenly-distribute-points-on-a-sphere-more-effectively-than-the-canonical-fibonacci-lattice/

source

GeoGrids._offset_ring Method
julia
_offset_ring(ring::Ring{🌐,<:LatLon{WGS84Latest}}, delta; magnitude=3, precision=7)

Offset a ring by a given delta value. This function uses the Clipper library for polygon offsetting. It may return multiple rings even when starting from a single Ring.

Arguments

  • ring::Ring{🌐,<:LatLon{WGS84Latest}}: The ring to be offset.
  • delta: The distance to offset the ring by. Positive for enlargement, negative for shrinking.
  • magnitude::Int=3: The number of integer digits for IntPoint conversion.
  • precision::Int=7: The total number of digits to be considered for each coordinate in IntPoint conversion.

Returns

  • Vector of Ring{🌐,<:LatLon{WGS84Latest}}: The resulting offset rings.

source

GeoGrids._points_required_for_separation_angle Method
julia
_points_required_for_separation_angle(angle::ValidAngle; spheRadius=1.0, pointsToCheck::Int=100, maxPrec=10^7, tol=10)

This function computes the minimum number of points required on the surface of a sphere to achieve a desired separation angle between any two adjacent points. The function uses the bisection method to find the minimum number of points needed and returns the higher end of the precision. Instead of checking all the possible pairs of the N points generated with the Fibonacci Spiral, only the first pointsToCheck are checked in order to evaluate the minimum separation angle.

Arguments:

  • sepAng: a float representing the desired separation angle between two adjacent points on the surface of the sphere.
  • spheRadius: an optional float representing the radius of the sphere. If not provided, it defaults to 1.0. This value is used to calculate the distance between points on the surface of the sphere. As default, the function assumes a unit sphere.
  • pointsToCheck: an optional integer representing the number of points to generate on the surface of the sphere. If not provided, it defaults to 100.
  • maxPrec: an optional integer representing the maximum precision for the number of points generated on the surface of the sphere. If not provided, it defaults to 10^7. Increasing this value will increase the precision of the result, but will also increase the time.
  • tol: an optional integer representing the tolerance for the bisection method used to find the minimum number of points needed to achieve the desired separation angle. If not provided, it defaults to 10. Reducing this value will increase the precision of the result but will also increase the time.

Output:

  • Ns[2]: an integer representing the minimum number of points required on the surface of the sphere to achieve the desired separation angle.
  • thisSep: an Uniful.Quantity in degrees representing the separation angle between two adjacent points on the surface of the sphere.

source

GeoGrids._tesselate Function
julia
_tesselate(points::AbstractVector{<:Point{🌐,<:LatLon{WGS84Latest}}}, method::TesselationMethod=VoronoiTesselation()) -> TesselationResult
_tesselate(point::Point{🌐,<:LatLon{WGS84Latest}}; kwargs...) -> TesselationResult

The function _tesselate uses tesselate from Meshes.jl is used to create a tasselation starting from a vector of geographical points (latitude and longitude) and tesselates them according to the specified tesselation method (default is VoronoiTesselation()). In this function, latitude is treated as the y-coordinate and longitude as the x-coordinate. The single point version of the function (_tesselate(point::Point{🌐,<:LatLon{WGS84Latest}}; kwargs...)) is a convenience method that allows you to tesselate a single point by internally converting it to a vector containing just that point.

Arguments

  • points::AbstractVector{<:Point{🌐,<:LatLon{WGS84Latest}}}: A vector of points defined in the WGS84 coordinate system. Each point represents a geographical location with latitude and longitude.
  • method::TesselationMethod=VoronoiTesselation(): The method used for tesselation. The default is VoronoiTesselation(), but other methods can be specified.

Keyword Arguments (for the second method signature)

  • kwargs...: Additional keyword arguments that will be passed to the first method.

Returns

  • TesselationResult: The result of the tesselation, which could be a set of polygons or other geometrical structures, depending on the tesselation method used.

source

GeoGrids._wrap_latlon Method
julia
_wrap_latlon(lat::Number, lon::Number)

The _wrap_latlon function normalizes and wraps geographic coordinates, latitude (lat) and longitude (lon). It ensures that the latitude is within the range [-90, 90] degrees and the longitude is within the range [-180, 180) degrees. This function is useful for handling geographic data where coordinates might exceed their typical bounds.

Arguments

  • lat::Number: The latitude value to be normalized and wrapped, expressed in degrees.
  • lon::Number: The longitude value to be normalized and wrapped, expressed in degrees.

Returns

  • Tuple{Number, Number}: A tuple (lat, lon) in degrees where lat is in the range [-90, 90] and lon is in the range [-180, 180).

source

GeoGrids.fibonaccisphere_alternative1 Method
julia
fibonaccisphere_alternative1(N::Int)

This function generates points on the surface of a unit sphere using the Fibonacci spiral method. The function takes an integer N as an input, which specifies the number of points to be generated.

Arguments

  • N::Int: The number of points to generate. This is an integer value.

Output

  • N x 3 matrix containing the generated points. Each row of the matrix corresponds to a point on the surface of the sphere, and the columns correspond to the x, y, and z coordinates of the point.

source

GeoGrids.fibonaccisphere_optimization1 Method
julia
fibonaccisphere_optimization1(N)

Create a set of N uniformly distributed points on the surface of a sphere using the Fibonacci spiral method optimized as described in [1].

This method is called Offset Fibonacci Lattice which is one method to optimize the minimum nearest-neighbor distance. We need to move (offset) all the points slightly farther away from the poles. This of course means, that almost all of them become slightly closer together. Offsetting the points of the Fibonacci lattice slightly away from the poles produces a packing that is up to 8.3% tighter than the canonical Fibonacci lattice.

For n>100, an improvement can be made beyond this, by initially placing a point at each pole, and then placing the remaining n-2 points. This not only (very sightly) improves minimal nearest packing, but it also prevents a large gap at each pole.

Arguments

  • N::Int: The number of points to generate.

Output

  • points::Matrix{Float64}: A Nx3 matrix where each row corresponds to a point (x,y,z) on the surface of the unitary sphere.

References

  1. http://extremelearning.com.au/how-to-evenly-distribute-points-on-a-sphere-more-effectively-than-the-canonical-fibonacci-lattice/

source

NearestNeighbors.knn Method
julia
knn(lltree::LatLonTree, points::Vector, k::Int [, sortres=false]) -> indices, distances

Performs a lookup of the k nearest neigbours to the points from the data in the lltree. points can either be a single coordinate expressed in LatLon or Point{🌐, <:LatLon} or a vector of such coordinates. skip is an optional predicate to determine if a point that would be returned should be skipped based on its index.

See also: knn!, nn.

source