GitHub

GridMaps

Quick Intro

This package provides the single, simple GridMap type and some associated methods. The typical use is to create a GridMap using a multi-dimensional array of data and bounds for all the dimensions of the region. Then individual values can be extracted by calling the created type with a desired multi-dimensional point.

Following is a quick example of the main functionality of this package.

julia> using Random; Random.seed!(0); # for repeatability
julia> using GridMaps
julia> data = reshape(1:25, 5, 5);
julia> bounds = (
           lower = [0.0, 0.0],
           upper = [1.0, 1.0]
       );
julia> gmap = GridMap(data, bounds) # stores the data and boundsGridMap{Int64} [[0.0, 0.0], [1.0, 1.0]]:
5×5 reshape(::UnitRange{Int64}, 5, 5) with eltype Int64:
 1   6  11  16  21
 2   7  12  17  22
 3   8  13  18  23
 4   9  14  19  24
 5  10  15  20  25
julia> val = gmap[1,4] # can directly access the underlying matrix16
julia> x = [.2, .75]; # a location/point
julia> val = gmap(x) # returns the value at a single 2D point17
julia> x, val = rand(gmap) # returns a random point and its value([0.4056994708920292, 0.06854582438651502], 3)
julia> getBounds(gmap) # can retrieve the bounds(lower = [0.0, 0.0], upper = [1.0, 1.0])
julia> res(gmap) # can calculate the cell resolutions2-element Vector{Float64}:
 0.25
 0.25
julia> ix = pointToCell(x, gmap) # converts a location to a cell indexCartesianIndex(3, 1)
julia> cellToPoint(CartesianIndex(1,4), gmap) # converts a cell index to a location2-element Vector{Float64}:
 0.0
 0.75
julia> generateAxes(gmap) # creates axes and points for all cells(StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}[0.0:0.25:1.0, 0.0:0.25:1.0], [[0.0, 0.0] [0.0, 0.25] … [0.0, 0.75] [0.0, 1.0]; [0.25, 0.0] [0.25, 0.25] … [0.25, 0.75] [0.25, 1.0]; … ; [0.75, 0.0] [0.75, 0.25] … [0.75, 0.75] [0.75, 1.0]; [1.0, 0.0] [1.0, 0.25] … [1.0, 0.75] [1.0, 1.0]])

Further Info

See below for further details on each type and method.

GridMaps.Bounds — Type
struct NamedTuple{(:lower, :upper), Tuple{Vector{Float64}, Vector{Float64}}}

The bounds of the region. Consists of the lower and upper bounds, each a list of floating-point values.

source
GridMaps.GridMap — Type

A general type for holding multi-dimensional data (usually a matrix) along with associated dimension bounds. It's main purpose is to handle the conversion between world coordinates and grid indices internally. Converting between the two representations treats rows as the first variable (x-axis), columns as the second (y-axis), and so on.

Its typical use is to act as a 2D map of some value that can be sampled. A GridMap will return the value of the grid cell that a given point falls within. In other words, the map value is constant within each cell. One can also think of this as a nearest-neighbor approximation.

Each cell index is treated as the center of its cell. Thus the map's lower bounds are at the center of the first cell and the map's upper bounds are at the center of the last cell.

Also made to function directly like a built-in N-dimensional array by sub-typing and implementing the base methods.

Fields:

  • data::AbstractArray: N-dimensional array of data

  • bounds::@NamedTuple{lower::Vector{Float64}, upper::Vector{Float64}}: vectors of lower and upper bounds, defaults to zeros and ones

A GridMap is constructed by passing the multi-dimensional array of data and the dimension bounds. If no bounds are passed, they default to zeros for lower and ones for upper.

Examples

data = reshape(1:25, 5, 5)
bounds = (
    lower = [0.0, 0.0],
    upper = [1.0, 1.0]
)
gmap = GridMap(data, bounds)
gmap2 = GridMap(data) # bounds will be zero to one
source
GridMaps.GridMap — Method

A variable of GridMap type can itself be called to retrieve map values. This method accepts a single vector (the location), returns a scalar (the value at that point).

Examples

data = reshape(1:25, 5, 5)
gmap = GridMap(data)

x = [.2, .75]
val = gmap(x) # returns the value at a single 2D point
val2 = gmap[1,4] # can also use as if it's just the underlying matrix
source
Base.rand — Method
rand(gmap::GridMap) -> Tuple{Vector{Float64}, Any}

Generates a random point within the map bounds. Returns a tuple of the location and its value.

source
GridMaps.cellToPoint — Method
cellToPoint(ci, gmap) -> Any

Takes in a CartesianIndex and a GridMap and returns a point in world-coordinates (a vector).

source
GridMaps.checkBounds — Method
checkBounds(x, gmap::GridMap) -> Any

Function emits error if location is outside of map bounds.

Examples

x = [.2, .75]
data = reshape(1:25, 5, 5)
gmap = GridMap(data)
checkBounds(x, gmap) # no error thrown
source
GridMaps.generateAxes — Method
generateAxes(gmap) -> Tuple{Any, Any}

Method to generate the x, y, etc. axes and points of a GridMap. Useful for plotting. ```

source
GridMaps.pointToCell — Method
pointToCell(x, gmap) -> Any

Takes in a point in world-coordinates (a vector) and a GridMap and returns a CartesianIndex for the underlying array.

source
GridMaps.randomPoint — Method
randomPoint(gmap::GridMap) -> Vector{Float64}

Generates a random point in the map. Returns the location.

source
GridMaps.res — Method
res(gmap) -> Any

Returns the resolution (distance between cells) for each dimension of the given GridMap as a vector.

source