#include <quetzal/geography/raster.hpp>

Detailed Description

template<typename Time = int>
class quetzal::geography::raster< Time >

Discrete spatio-temporal variations of an environmental variable.

Read and write georeferenced raster datasets with multiple bands (layers). Multiple rasters can be assembled into a multivariate discrete quetzal::geography::landscape.

Public Types
using	time_type = Time

using	time_descriptor = std::vector< time_type >::size_type

using	location_descriptor = int

using	latlon = quetzal::geography::latlon

using	lonlat = quetzal::geography::lonlat

using	colrow = quetzal::geography::colrow

using	rowcol = quetzal::geography::rowcol

using	decimal_degree = double

using	value_type = double

Public Member Functions
	raster (const std::filesystem::path &file, const std::vector< time_type > &times)
	Constructor.

Spatial Grid properties
latlon	origin () const noexcept
	Origin of the spatial grid.

geography::resolution< decimal_degree >	get_resolution () const noexcept
	Resolution of the spatial grid.

geography::extent< decimal_degree >	get_extent () const noexcept
	Extent of the spatial grid.

int	width () const noexcept
	Width of the spatial grid.

int	height () const noexcept
	Height of the spatial grid.

int	depth () const noexcept
	Depth of the spatial grid.

value_type	NA () const noexcept
	NA value, as read in the first band of the dataset.

Look-up
auto	locations () const noexcept
	Location descriptors (unique identifiers) of the grid cells.

auto	times () const noexcept
	Time descriptors (unique identifiers) of the dataset bands.

bool	is_valid (location_descriptor x) const noexcept
	Check if a descriptor describes a valid location of the spatial grid.

bool	is_valid (const colrow &x) const noexcept
	Check if the coordinate describes a valid location of the spatial grid.

bool	is_valid (const rowcol &x) const noexcept
	Check if the coordinate describes a valid location of the spatial grid.

bool	contains (const latlon &x) const noexcept
	Check if the raster contains a coordinate.

bool	contains (const lonlat &x) const noexcept
	Check if the raster contains a coordinate.

bool	is_valid (time_descriptor t) const noexcept
	Check if the time descriptor is a valid index.

bool	is_recorded (const time_type &t) const noexcept
	Search for the exact time in the list of time points recorded by the raster.

bool	is_in_interval (const time_type &t) const noexcept
	Check if the exact time point falls between the first and last date of record.

std::optional< value_type >	at (location_descriptor x, time_descriptor t) const noexcept
	Read the value at location x and time t.

auto	to_view () const noexcept
	Makes the raster a callable with signature `std::optional<value_type> (location_descriptor x, time_descriptor t)` returning the value at location x and time t.

Coordinate systems
location_descriptor	to_descriptor (const colrow &x) const noexcept
	Location descriptor of the cell identified by its column/row.

location_descriptor	to_descriptor (const latlon &x) const noexcept
	Location descriptor of the cell to which the given coordinate belongs.

colrow	to_colrow (const latlon &x) const noexcept
	Column and row of the cell to which the given coordinate belongs.

rowcol	to_rowcol (const latlon &x) const noexcept
	Row and column of the cell to which the given coordinate belongs.

colrow	to_colrow (location_descriptor x) const noexcept
	Column and row of the cell to which the given descriptor belongs.

rowcol	to_rowcol (location_descriptor x) const noexcept
	Column and row of the cell to which the given descriptor belongs.

latlon	to_latlon (location_descriptor x) const noexcept
	Latitude and longitude of the cell to which the given coordinate belongs.

lonlat	to_lonlat (location_descriptor x) const noexcept
	Latitude and longitude of the cell to which the given coordinate belongs.

latlon	to_latlon (const colrow &x) const noexcept
	Latitude and longitude of the cell identified by its column/row.

latlon	to_latlon (const rowcol &x) const noexcept
	Latitude and longitude of the cell identified by its row/column.

lonlat	to_lonlat (const colrow &x) const noexcept
	Longitude and latitude of the deme identified by its column/row.

latlon	to_centroid (const latlon &x) const
	Reprojects a coordinate to the centroid of the cell it belongs.

Input/Output
template<class Callable > requires (std::is_invocable_r_v<std::optional<value_type>, Callable, location_descriptor, time_type>)
void	to_geotiff (Callable f, time_type start, time_type end, const std::filesystem::path &file) const
	Export a spatio-temporal raster to a Geotiff file.

void	to_shapefile (std::vector< latlon > points, const std::filesystem::path &file) const
	Export spatial points to a shapefile.

void	to_shapefile (std::map< latlon, int > counts, const std::filesystem::path &file) const
	Export geolocalized counts as spatial-points to a shapefile.

std::ostream &	write (std::ostream &stream) const
	Raster is streamable.

static raster	from_file (const std::filesystem::path &file, const std::vector< time_type > &times)
	Read the raster from an input file in the geotiff format.

Constructor & Destructor Documentation

◆ raster()

template<typename Time = int>

quetzal::geography::raster< Time >::raster	(	const std::filesystem::path &	file,
		const std::vector< time_type > &	times
	)

inlineexplicit

Constructor.

Parameters

file	the raster dataset file to read.
times	the time period of each layer

Invariant: The size of the times argument equals the depth of the given dataset

Member Function Documentation

◆ at()

template<typename Time = int>

std::optional< value_type > quetzal::geography::raster< Time >::at	(	location_descriptor	x,
		time_descriptor	t
	)		const

inlinenoexcept

Read the value at location x and time t.

Parameters

x	the location
t	the time

Returns: An optional that is empty if the value read is equal to NA.

Precondition: x is contained in the spatial extent; t is contained in the temporal extent

◆ contains() [1/2]

template<typename Time = int>

bool quetzal::geography::raster< Time >::contains ( const latlon & x ) const

inlinenoexcept

Check if the raster contains a coordinate.

Parameters

x	the lat/lon to check.

Returns: True if x is valid, false otherwise.

◆ contains() [2/2]

template<typename Time = int>

bool quetzal::geography::raster< Time >::contains ( const lonlat & x ) const

inlinenoexcept

Check if the raster contains a coordinate.

Parameters

x	the lon/lat to check.

Returns: True if x is valid, false otherwise.

◆ from_file()

template<typename Time = int>

static raster quetzal::geography::raster< Time >::from_file	(	const std::filesystem::path &	file,
		const std::vector< time_type > &	times
	)

inlinestatic

Read the raster from an input file in the geotiff format.

Parameters

file	The file to read from
times	The time periods relative to each band.

Returns: A raster object

◆ get_resolution()

template<typename Time = int>

geography::resolution< decimal_degree > quetzal::geography::raster< Time >::get_resolution ( ) const

inlinenoexcept

Resolution of the spatial grid.

Note: The vertical pixel size will be negative (south pointing)

◆ is_in_interval()

template<typename Time = int>

bool quetzal::geography::raster< Time >::is_in_interval ( const time_type & t ) const

inlinenoexcept

Check if the exact time point falls between the first and last date of record.

Parameters

t	An exact point in time

Returns: True if the time point falls in the temporal range, false otherwise.

◆ is_recorded()

template<typename Time = int>

bool quetzal::geography::raster< Time >::is_recorded ( const time_type & t ) const

inlinenoexcept

Search for the exact time in the list of time points recorded by the raster.

Parameters

t	An exact point in time

Returns: True if the time point is found, false otherwise.

◆ is_valid() [1/4]

template<typename Time = int>

bool quetzal::geography::raster< Time >::is_valid ( const colrow & x ) const

inlinenoexcept

Check if the coordinate describes a valid location of the spatial grid.

Parameters

x	the column/row to check.

Returns: True if x is valid, false otherwise.

◆ is_valid() [2/4]

template<typename Time = int>

bool quetzal::geography::raster< Time >::is_valid ( const rowcol & x ) const

inlinenoexcept

Check if the coordinate describes a valid location of the spatial grid.

Parameters

x	the row/column to check.

Returns: True if x is valid, false otherwise.

◆ is_valid() [3/4]

template<typename Time = int>

bool quetzal::geography::raster< Time >::is_valid ( location_descriptor x ) const

inlinenoexcept

Check if a descriptor describes a valid location of the spatial grid.

Parameters

x	the descriptor to check

Returns: True if x is valid, false otherwise.

◆ is_valid() [4/4]

template<typename Time = int>

bool quetzal::geography::raster< Time >::is_valid ( time_descriptor t ) const

inlinenoexcept

Check if the time descriptor is a valid index.

Parameters

t	A time descriptor identifying a band of the raster dataset.

Returns: True if t is a valid index, false otherwise.

◆ locations()

template<typename Time = int>

auto quetzal::geography::raster< Time >::locations ( ) const

inlinenoexcept

Location descriptors (unique identifiers) of the grid cells.

Returns: A range of unique identifiers for every cell

◆ times()

template<typename Time = int>

auto quetzal::geography::raster< Time >::times ( ) const

inlinenoexcept

Time descriptors (unique identifiers) of the dataset bands.

Returns: A range of unique identifiers for every time point recorded

◆ to_centroid()

template<typename Time = int>

latlon quetzal::geography::raster< Time >::to_centroid ( const latlon & x ) const

inline

Reprojects a coordinate to the centroid of the cell it belongs.

Precondition: The spatial extent of the raster must contain the coordinate.

Parameters

x	The location to reproject

Returns: The coordinate of the centroid of the cell it belongs.

Precondition: x is in the spatial extent

◆ to_colrow() [1/2]

template<typename Time = int>

colrow quetzal::geography::raster< Time >::to_colrow ( const latlon & x ) const

inlinenoexcept

Column and row of the cell to which the given coordinate belongs.

Parameters

x	the latitude/longitude coordinate to evaluate.

Returns: A pair (column, row).

Precondition: x is in the spatial extent.

◆ to_colrow() [2/2]

template<typename Time = int>

colrow quetzal::geography::raster< Time >::to_colrow ( location_descriptor x ) const

inlinenoexcept

Column and row of the cell to which the given descriptor belongs.

Parameters

x	the location to evaluate.

Returns: A pair (column, row).

Precondition: x is in the spatial extent.

◆ to_descriptor() [1/2]

template<typename Time = int>

location_descriptor quetzal::geography::raster< Time >::to_descriptor ( const colrow & x ) const

inlinenoexcept

Location descriptor of the cell identified by its column/row.

Parameters

x	the 1D coordinate to evaluate.

Returns: The descriptor value of x.

Precondition: x is in spatial extent.

◆ to_descriptor() [2/2]

template<typename Time = int>

location_descriptor quetzal::geography::raster< Time >::to_descriptor ( const latlon & x ) const

inlinenoexcept

Location descriptor of the cell to which the given coordinate belongs.

Parameters

x	the latitude/longitude coordinate to evaluate.

Returns: The descriptor value of x.

Precondition: x is in the spatial extent.

◆ to_geotiff()

template<typename Time = int>

template<class Callable >
requires (std::is_invocable_r_v<std::optional<value_type>, Callable, location_descriptor, time_type>)

void quetzal::geography::raster< Time >::to_geotiff	(	Callable	f,
		time_type	start,
		time_type	end,
		const std::filesystem::path &	file
	)		const

inline

Export a spatio-temporal raster to a Geotiff file.

Parameters

f	functor defining the variable: its signature should be equivalent to `std::optional<double> f(location_descriptor, time_descriptor)`
start	the first time_descriptor value where f should be called.
end	the last time_descriptor value where f should be called.
file	the file name where to save

Remarks: If the returned optional is empty, the raster NA value will be used.

◆ to_latlon() [1/3]

template<typename Time = int>

latlon quetzal::geography::raster< Time >::to_latlon ( const colrow & x ) const

inlinenoexcept

Latitude and longitude of the cell identified by its column/row.

Parameters

x	the location to evaluate.

Returns: A pair (latitude, longitude)

Precondition: x is in the spatial extent

◆ to_latlon() [2/3]

template<typename Time = int>

latlon quetzal::geography::raster< Time >::to_latlon ( const rowcol & x ) const

inlinenoexcept

Latitude and longitude of the cell identified by its row/column.

Parameters

x	the location to evaluate.

Returns: A pair (latitude, longitude).

Precondition: x is in the spatial extent.

◆ to_latlon() [3/3]

template<typename Time = int>

latlon quetzal::geography::raster< Time >::to_latlon ( location_descriptor x ) const

inlinenoexcept

Latitude and longitude of the cell to which the given coordinate belongs.

Parameters

x	the location to evaluate.

Returns: A pair (lat, lon).

Precondition: x is in the spatial extent.

◆ to_lonlat() [1/2]

template<typename Time = int>

lonlat quetzal::geography::raster< Time >::to_lonlat ( const colrow & x ) const

inlinenoexcept

Longitude and latitude of the deme identified by its column/row.

Parameters

x	the location to evaluate.

Returns: A pair (longitude, latitude).

Precondition: x is in the spatial extent.

◆ to_lonlat() [2/2]

template<typename Time = int>

lonlat quetzal::geography::raster< Time >::to_lonlat ( location_descriptor x ) const

inlinenoexcept

Latitude and longitude of the cell to which the given coordinate belongs.

Parameters

x	the location to evaluate.

Returns: A pair (lon, lat).

Precondition: x is in the spatial extent

◆ to_rowcol() [1/2]

template<typename Time = int>

rowcol quetzal::geography::raster< Time >::to_rowcol ( const latlon & x ) const

inlinenoexcept

Row and column of the cell to which the given coordinate belongs.

Parameters

x	the latitude/longitude coordinate to evaluate.

Returns: A pair (row, column).

Precondition: x is in the spatial extent.

◆ to_rowcol() [2/2]

template<typename Time = int>

rowcol quetzal::geography::raster< Time >::to_rowcol ( location_descriptor x ) const

inlinenoexcept

Column and row of the cell to which the given descriptor belongs.

Parameters

x	the location to evaluate.

Returns: A pair (column, row).

Precondition: x is in the spatial extent.

◆ to_shapefile() [1/2]

template<typename Time = int>

void quetzal::geography::raster< Time >::to_shapefile	(	std::map< latlon, int >	counts,
		const std::filesystem::path &	file
	)		const

inline

Export geolocalized counts as spatial-points to a shapefile.

counts the number of points at every point

file the path to write to.

◆ to_shapefile() [2/2]

template<typename Time = int>

void quetzal::geography::raster< Time >::to_shapefile	(	std::vector< latlon >	points,
		const std::filesystem::path &	file
	)		const

inline

Export spatial points to a shapefile.

Parameters

points	the points to export
file	the path to write to

◆ to_view()

template<typename Time = int>

auto quetzal::geography::raster< Time >::to_view ( ) const

inlinenoexcept

Makes the raster a callable with signature std::optional<value_type> (location_descriptor x, time_descriptor t) returning the value at location x and time t.

Remarks: This callable is cheap to copy, does not have ownership of the data, and works well for mathematical composition using quetzal::expressive

The documentation for this class was generated from the following file:

/home/runner/work/quetzal-CoaTL/quetzal-CoaTL/src/include/quetzal/geography/raster.hpp

Detailed Description

Public Types

Public Member Functions

Input/Output

Constructor & Destructor Documentation

◆ raster()

Member Function Documentation

◆ at()

◆ contains() [1/2]

◆ contains() [2/2]

◆ from_file()

◆ get_resolution()

◆ is_in_interval()

◆ is_recorded()

◆ is_valid() [1/4]

◆ is_valid() [2/4]

◆ is_valid() [3/4]

◆ is_valid() [4/4]

◆ locations()

◆ times()

◆ to_centroid()

◆ to_colrow() [1/2]

◆ to_colrow() [2/2]

◆ to_descriptor() [1/2]

◆ to_descriptor() [2/2]

◆ to_geotiff()

◆ to_latlon() [1/3]

◆ to_latlon() [2/3]

◆ to_latlon() [3/3]

◆ to_lonlat() [1/2]

◆ to_lonlat() [2/2]

◆ to_rowcol() [1/2]

◆ to_rowcol() [2/2]

◆ to_shapefile() [1/2]

◆ to_shapefile() [2/2]

◆ to_view()