#include <quetzal/geography/landscape.hpp>

Detailed Description

template<typename Key = std::string, typename Time = int>
class quetzal::geography::landscape< Key, Time >

Discrete spatio-temporal variations of a set of environmental variables.

Read and write multiple geo-referenced raster datasets with multiple bands (layers). Multiple quetzal::geography::raster objects are assembled into a multivariate discrete quetzal::geography::landscape. This geo-spatial collection is constructed from raster files and gives strong guarantees on grids consistency.

Remarks: Working with multiple variables can lead to simulation problems if the rasters have even slightly different grid properties, like different resolutions, origins or extent. To prevent these problems from happening, a quetzal::geography::landscape wraps multiple quetzal::geography::raster objects into one single coherent object and checks that all rasters are aligned.; A quetzal::geography::landscape shares a large part of its spatial semantics with a quetzal::geography::raster.

Template Parameters

Key	A key used to uniquely identify a variable, e.g. std::string.
Time	Type used as time period for every band, e.g. std::string with `4.2-0.3 ka`

Public Types
using	key_type = Key

using	time_type = Time

using	location_descriptor = typename raster< time_type >::location_descriptor

using	time_descriptor = typename raster< time_type >::time_descriptor

using	latlon = typename raster< time_type >::latlon

using	lonlat = typename raster< time_type >::lonlat

using	colrow = typename raster< time_type >::colrow

using	rowcol = typename raster< time_type >::rowcol

using	decimal_degree = typename raster< time_type >::decimal_degree

Public Member Functions
Capacity
auto	num_variables () const noexcept
	Retrieves the number of variables (rasters)

auto	num_locations () const noexcept
	Number of cells in the raster.

Element access
const raster< time_type > &	operator[] (const key_type &key) const
	Returns a const reference to the mapped raster with key equivalent to `key`. If no such raster exists, an exception of type std::out_of_range is thrown.

raster< time_type > &	operator[] (const key_type &key)
	Returns a reference to the mapped raster with key equivalent to `key`. If no such raster exists, an exception of type std::out_of_range is thrown.

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

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

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.

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.

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.

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
	Longitude and latitude 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.

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
static landscape	from_file (const std::map< key_type, std::filesystem::path > &files, const std::vector< time_type > &times)
	Read the rasters from a set of input geotiff files.

template<typename Callable > requires std::invocable<Callable, location_descriptor, time_descriptor, std::optional<double>>
void	to_geotiff (Callable f, time_descriptor start, time_descriptor 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
	Landscape is streamable.

Member Function Documentation

◆ contains() [1/2]

template<typename Key = std::string, typename Time = int>

bool quetzal::geography::landscape< Key, 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 Key = std::string, typename Time = int>

bool quetzal::geography::landscape< Key, 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 Key = std::string, typename Time = int>

static landscape quetzal::geography::landscape< Key, Time >::from_file	(	const std::map< key_type, std::filesystem::path > &	files,
		const std::vector< time_type > &	times
	)

inlinestatic

Read the rasters from a set of input geotiff files.

Parameters

files	A map giving as keys the name of a variable, and as value a path to read it from.
start	The first time period to map to the first band
end	The last time period to map to the last band
step	The time increment between each band

Returns: A raster object

Remarks: error will be thrown if the datasets do not have the exactly same geographical properties (origin, extent, resolution, number of layers).

◆ is_in_interval()

template<typename Key = std::string, typename Time = int>

bool quetzal::geography::landscape< Key, 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 Key = std::string, typename Time = int>

bool quetzal::geography::landscape< Key, 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 Key = std::string, typename Time = int>

bool quetzal::geography::landscape< Key, 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 Key = std::string, typename Time = int>

bool quetzal::geography::landscape< Key, 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 Key = std::string, typename Time = int>

bool quetzal::geography::landscape< Key, 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 Key = std::string, typename Time = int>

bool quetzal::geography::landscape< Key, Time >::is_valid ( time_descriptor t ) const

inlinenoexcept

Check if the time descriptor is a valid index.

Parameters

t	A time descriptor identifying a layer of the raster.

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

◆ locations()

template<typename Key = std::string, typename Time = int>

auto quetzal::geography::landscape< Key, Time >::locations ( ) const

inlinenoexcept

Location descriptors (unique identifiers) of the grid cells.

Returns: A range of unique identifiers for every cell

◆ num_locations()

template<typename Key = std::string, typename Time = int>

auto quetzal::geography::landscape< Key, Time >::num_locations ( ) const

inlinenoexcept

Number of cells in the raster.

Returns: the number of variables

◆ num_variables()

template<typename Key = std::string, typename Time = int>

auto quetzal::geography::landscape< Key, Time >::num_variables ( ) const

inlinenoexcept

Retrieves the number of variables (rasters)

Returns: the number of variables

◆ operator[]() [1/2]

template<typename Key = std::string, typename Time = int>

raster< time_type > & quetzal::geography::landscape< Key, Time >::operator[] ( const key_type & key )

inline

Returns a reference to the mapped raster with key equivalent to key. If no such raster exists, an exception of type std::out_of_range is thrown.

Parameters

key	the identifier of the variable to be retrieved

Returns: the raster object of the specified variable.

◆ operator[]() [2/2]

template<typename Key = std::string, typename Time = int>

const raster< time_type > & quetzal::geography::landscape< Key, Time >::operator[] ( const key_type & key ) const

inline

Returns a const reference to the mapped raster with key equivalent to key. If no such raster exists, an exception of type std::out_of_range is thrown.

Parameters

key	the identifier of the variable to be retrieved

Returns: the raster object of the specified variable.

◆ times()

template<typename Key = std::string, typename Time = int>

auto quetzal::geography::landscape< Key, 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 Key = std::string, typename Time = int>

latlon quetzal::geography::landscape< Key, Time >::to_centroid ( const latlon & x ) const

inline

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

Precondition: The landscape must contain the coordinate in its spatial extent.

Parameters

x	The location to reproject

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

Precondition: x is in spatial extent

◆ to_colrow() [1/2]

template<typename Key = std::string, typename Time = int>

colrow quetzal::geography::landscape< Key, Time >::to_colrow ( const latlon & x ) const

inlinenoexcept

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

Parameters

x	the coordinate to evaluate.

Returns: A pair (column, row).

Precondition: x is in spatial extent.

◆ to_colrow() [2/2]

template<typename Key = std::string, typename Time = int>

colrow quetzal::geography::landscape< Key, 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 spatial extent.

◆ to_descriptor() [1/2]

template<typename Key = std::string, typename Time = int>

location_descriptor quetzal::geography::landscape< Key, Time >::to_descriptor ( const colrow & x ) const

inlinenoexcept

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

Parameters

x	the coordinate to evaluate.

Returns: The descriptor value.

Precondition: x is in spatial extent.

◆ to_descriptor() [2/2]

template<typename Key = std::string, typename Time = int>

location_descriptor quetzal::geography::landscape< Key, Time >::to_descriptor ( const latlon & x ) const

inlinenoexcept

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

Parameters

x	the coordinate to evaluate.

Returns: The descriptor value.

Precondition: x is in spatial extent.

◆ to_geotiff()

template<typename Key = std::string, typename Time = int>

template<typename Callable >
requires std::invocable<Callable, location_descriptor, time_descriptor, std::optional<double>>

void quetzal::geography::landscape< Key, Time >::to_geotiff	(	Callable	f,
		time_descriptor	start,
		time_descriptor	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 `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

◆ to_latlon() [1/2]

template<typename Key = std::string, typename Time = int>

latlon quetzal::geography::landscape< Key, 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 spatial extent.

◆ to_latlon() [2/2]

template<typename Key = std::string, typename Time = int>

latlon quetzal::geography::landscape< Key, 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 spatial extent.

◆ to_lonlat() [1/2]

template<typename Key = std::string, typename Time = int>

lonlat quetzal::geography::landscape< Key, 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 spatial extent

◆ to_lonlat() [2/2]

template<typename Key = std::string, typename Time = int>

lonlat quetzal::geography::landscape< Key, Time >::to_lonlat ( location_descriptor x ) const

inlinenoexcept

Longitude and latitude of the cell to which the given coordinate belongs.

Parameters

x	the location to evaluate.

Returns: A pair (lon, lat).

Precondition: x is in spatial extent

◆ to_rowcol()

template<typename Key = std::string, typename Time = int>

rowcol quetzal::geography::landscape< Key, Time >::to_rowcol ( const latlon & x ) const

inlinenoexcept

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

Parameters

x	the coordinate to evaluate.

Returns: A pair (row, column).

Precondition: x is in spatial extent.

◆ to_shapefile() [1/2]

template<typename Key = std::string, typename Time = int>

void quetzal::geography::landscape< Key, 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 Key = std::string, typename Time = int>

void quetzal::geography::landscape< Key, 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

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

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

Detailed Description

Public Types

Public Member Functions

Input/Output

Member Function Documentation

◆ contains() [1/2]

◆ contains() [2/2]

◆ from_file()

◆ is_in_interval()

◆ is_recorded()

◆ is_valid() [1/4]

◆ is_valid() [2/4]

◆ is_valid() [3/4]

◆ is_valid() [4/4]

◆ locations()

◆ num_locations()

◆ num_variables()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ times()

◆ to_centroid()

◆ to_colrow() [1/2]

◆ to_colrow() [2/2]

◆ to_descriptor() [1/2]

◆ to_descriptor() [2/2]

◆ to_geotiff()

◆ to_latlon() [1/2]

◆ to_latlon() [2/2]

◆ to_lonlat() [1/2]

◆ to_lonlat() [2/2]

◆ to_rowcol()

◆ to_shapefile() [1/2]

◆ to_shapefile() [2/2]