Classes
struct	sgs::helper::Index
struct	sgs::helper::Field
struct	sgs::helper::RasterBandMetaData
struct	sgs::helper::VRTBandDatasetInfo
class	sgs::helper::Variance
struct	sgs::helper::PointHash

Typedefs
typedef boost::unordered::unordered_flat_map< std::pair< int, int >, std::vector< std::pair< double, double > >, PointHash >	sgs::helper::NeighborMap

Functions
void	sgs::helper::setStratBandTypeAndSize (size_t maxStrata, GDALDataType p_type, size_t p_size)
template<typename T>
T	sgs::helper::getPixelValueDependingOnType (GDALDataType type, void *p_data, size_t index)
void	sgs::helper::setStrataPixelDependingOnType (GDALDataType type, void *p_data, size_t index, bool isNan, size_t strata)
void	sgs::helper::printTypeWarningsForInt32Conversion (GDALDataType type)
GDALDataset *	sgs::helper::createVirtualDataset (std::string driverName, int width, int height, double *geotransform, std::string projection)
GDALDataset *	sgs::helper::createDataset (std::string filename, std::string driverName, int width, int height, double geotransform, std::string projection, RasterBandMetaData bands, size_t bandCount, bool useTiles, std::map< std::string, std::string > &driverOptions)
void	sgs::helper::addBandToMEMDataset (GDALDataset *p_dataset, RasterBandMetaData &band)
void	sgs::helper::createVRTBandDataset (GDALDataset *p_dataset, RasterBandMetaData &band, std::string tempFolder, std::string key, std::vector< VRTBandDatasetInfo > &VRTBandInfo, std::map< std::string, std::string > &driverOptions)
void	sgs::helper::addBandToVRTDataset (GDALDataset *p_dataset, RasterBandMetaData &band, VRTBandDatasetInfo &info)
void	sgs::helper::rasterBandIO (RasterBandMetaData &band, void *p_buffer, int xBlockSize, int yBlockSize, int xBlock, int yBlock, int xValid, int yValid, bool read, bool threaded=true)
void	sgs::helper::addPoint (OGRPoint p_point, OGRLayer p_layer)
void	sgs::helper::addPoint (const OGRPoint p_point, OGRLayer p_layer)
void	sgs::helper::addPoint (OGRPoint p_point, OGRLayer p_layer, Field *p_field)
void	sgs::helper::addPoint (const OGRPoint p_point, OGRLayer p_layer, Field *p_field)
void	sgs::helper::addPoint (OGRPoint p_point, OGRLayer p_layer, std::vector< Field * > *p_fields)
void	sgs::helper::addPoint (const OGRPoint p_point, OGRLayer p_layer, std::vector< Field * > *p_fields)
template<typename T>
T	sgs::helper::point2index (double xCoord, double yCoord, double *IGT, T width)
uint64_t	sgs::helper::getProbabilityMultiplier (double width, double height, double pixelWidth, double pixelHeight, int startMult, int numSamples, bool useMindist, double accessibleArea)
bool	sgs::helper::is_valid_sample (double x, double y, NeighborMap &neighbor_map, float mindist, float mindist_sq)
std::pair< double, double >	sgs::helper::sample_to_point (double *GT, Index &index)
std::pair< double, double >	sgs::helper::sample_to_point (double *GT, int xs, int ys)

Detailed Description

Typedef Documentation

◆ NeighborMap

typedef boost::unordered::unordered_flat_map<std::pair<int, int>, std::vector<std::pair<double, double> >, PointHash> sgs::helper::NeighborMap

This is a type alias for the neighborhood used for spatial hashing during sampling.

Function Documentation

◆ addBandToMEMDataset()

void sgs::helper::addBandToMEMDataset	(	GDALDataset *	p_dataset,
		RasterBandMetaData &	band )

inline

This helper function dynamically adds a raster band to an existing in-memory dataset (MEM).

First, the buffer is allocated according to the height, width, and pixel size of the entire band. This buffer is passed as the 'datapointer' option to the AddBand function so that the memory is now associated with the dataset.

Once the band has been created, it's name and nodata values are set, and the RasterBandMetaData struct of the particular raster band which was added is updated with a pointer to the GDALRasterBand object.

Parameters

GDALDataset	*p_dataset
RasterBandMetaData&	band

◆ addBandToVRTDataset()

void sgs::helper::addBandToVRTDataset	(	GDALDataset *	p_dataset,
		RasterBandMetaData &	band,
		VRTBandDatasetInfo &	info )

inline

This helper function adds an existing raster dataset as a band to an existing VRT dataset.

First, creation options are determined. The filename, as well as the VRT band subclass are added as options. Then, the band is added and updated with a name and nodata value.

Parameters

GDALDataset	*p_dataset
RasterBandMetaData&	band
VRTBandDatasetInfo&	info

◆ addPoint() [1/6]

void sgs::helper::addPoint	(	const OGRPoint *	p_point,
		OGRLayer *	p_layer )

inline

Helper function to add a point to a layer. This is the version which will be called when there is a const OGRPoint *.

Parameters

OGRPoint	*p_point
OGRLayer	*p_layer

◆ addPoint() [2/6]

void sgs::helper::addPoint	(	const OGRPoint *	p_point,
		OGRLayer *	p_layer,
		Field *	p_field )

inline

Helper function to add a point to a layer, with an additional field value. This is the version which will be called when there is a const OGRPoint *.

Parameters

OGRPoint	*p_point
OGRLayer	*p_layer
std::vector<Field>

◆ addPoint() [3/6]

void sgs::helper::addPoint	(	const OGRPoint *	p_point,
		OGRLayer *	p_layer,
		std::vector< Field * > *	p_fields )

inline

Helper function to add a point to a layer, with additional field values. This is the version which will be called when there is a const OGRPoint *.

Parameters

OGRPoint	*p_point
OGRLayer	*p_layer
std::vector<Field>

◆ addPoint() [4/6]

void sgs::helper::addPoint	(	OGRPoint *	p_point,
		OGRLayer *	p_layer )

inline

Helper function to add a point to a layer.

Parameters

OGRPoint	*p_point
OGRLayer	*p_layer

◆ addPoint() [5/6]

void sgs::helper::addPoint	(	OGRPoint *	p_point,
		OGRLayer *	p_layer,
		Field *	p_field )

inline

Helper function to add a point to a layer, with an additional field value.

Parameters

OGRPoint	*p_point
OGRLayer	*p_layer
std::vector<Field>

◆ addPoint() [6/6]

void sgs::helper::addPoint	(	OGRPoint *	p_point,
		OGRLayer *	p_layer,
		std::vector< Field * > *	p_fields )

inline

Helper function to add a point to a layer, with additional field values.

Parameters

OGRPoint	*p_point
OGRLayer	*p_layer
std::vector<Field>

◆ createDataset()

GDALDataset * sgs::helper::createDataset	(	std::string	filename,
		std::string	driverName,
		int	width,
		int	height,
		double *	geotransform,
		std::string	projection,
		RasterBandMetaData *	bands,
		size_t	bandCount,
		bool	useTiles,
		std::map< std::string, std::string > &	driverOptions )

inline

This helper function is used when the user provides a specific filename, and creates a dataset using the driver associated with the filename extension.

Note, the driverName must be determined from the filename before this function is called.

First, a GDALDriver is created with the driver according to the driverName parameter. Then, if tiles should be used, those CSL options are added to a CSL options list which will be passed when creating the Dataset. User-given driver options are also added to teh CSL options list.

A dataset is created using the filename, height, width, band count, and options specified. Note, the type of every raster in the dataset must be the same (this is true right now, as the only driver allowed is tiff, this may be changed in the future as more drivers are added.

The geotransform and projection are set.

Finally, since the band information (specifically type) must be known before a non-virtual dataset is created, the RasterBandMetaData structs associated with each band have not been fully populated. Bands could not habve been allocated, created, etc. until after all of them had been iterated through. Now that we are able to create the dataset with its associated bands, we must now populate the RasterBandMetaData structs with the remaining meta data including block sizes and GDALRasterBand pointers. The name and nodata value of each band is also updated.

Parameters

std::string	filename
std::string	driverName
int	width
int	height
double	*geotransform
std::string	projection,k
RasterBandMetaData	*bands
size_t	bandCount
bool	useTiles

Returns: GDALDataset *

◆ createVirtualDataset()

GDALDataset * sgs::helper::createVirtualDataset	(	std::string	driverName,
		int	width,
		int	height,
		double *	geotransform,
		std::string	projection )

inline

This helper function is used by stratification functions to create a virtual dataset to add bands to. The virtual dataset will either be a MEM dataset or in-memory dataset, or a VRT dataset. The VRT dataset will be chosen if the raster is large enough that putting the whole raster into memory should not be attempted.

The function begins by getting a GDALDriver from the driver name (which must be one of "MEM" or "VRT").

Then, a new GDALDataset is created with the width and height required. Type, band number, filename, and other options are not used because the bands will be dynamically added with potentially different types per band, and this dataset will not be written directly to disk.

The geotransform and projection are set.

Parameters

std::string	driverName
int	width
int	height
double	*geotransform
std::string	projection

Returns: GDALDataset *

◆ createVRTBandDataset()

void sgs::helper::createVRTBandDataset	(	GDALDataset *	p_dataset,
		RasterBandMetaData &	band,
		std::string	tempFolder,
		std::string	key,
		std::vector< VRTBandDatasetInfo > &	VRTBandInfo,
		std::map< std::string, std::string > &	driverOptions )

inline

This helper function is used to create a dataset which will be used as the band of a VRT dataset. In order to pass the checks for the addition of a dataset as a band to a VRT dataset the file must be populated (written to). This function is used before any data processing is undertaken to create an empty tif file, so that data has a place to be written to, and is added as a band to a VRT dataset once the processing has completed.

When this function has completed there will be a new entry in the VRTBandInfo vector containing a dataset pointer and filename. The RasterBandMetaData object will also be updated with the band information for the tif file created. It's worth noting that the tmpPath is a temporary folder created for the SpatialRaster which this function was called, that holds the .tif files which make up the VRT dataset.

first, the full file path is determined using the temp path, as well as a unique key differentiating the different bands which may be in the dataset. The useTiles boolean determines whether the TILED, XBLOCKSIZE, and YBLOCKSIZE options will be used in dataset creation. The reason why they wouldn't be used is if the block size is a scanline – this is because GDAL will throw an error if the tile array would be larger than 2GB, which would happen if tiles were scanlines on some large images. Then, the geotransform is determined, and createDataset() is called.

Finally, the new tif datasets only band is updated with a name, and nodata value, and the corresponding RasterBandMetaData object is updated.

Parameters

GDALDataset	*p_dataset
RasterBandMetaData&	data
std::string	tempFolder
std::string	key
std::vector<VRTBandDatasetInfo>&	VRTBandInfo
std::map<std::string,std::string>&	driverOptions

◆ getPixelValueDependingOnType()

template<typename T>

T sgs::helper::getPixelValueDependingOnType	(	GDALDataType	type,
		void *	p_data,
		size_t	index )

inline

Helper function for reading a particular pixel from a raster data buffer. The data buffer is cast to the type corresponding to the GDALDataType type parameter, then indexed. The resulting value is then cast to the double type.

Parameters

GDALDataType	type
void	*p_data
size_t	index

Returns: T

◆ getProbabilityMultiplier()

uint64_t sgs::helper::getProbabilityMultiplier	(	double	width,
		double	height,
		double	pixelWidth,
		double	pixelHeight,
		int	startMult,
		int	numSamples,
		bool	useMindist,
		double	accessibleArea )

inline

This is a helper function used for determine the probability multiplier for a given raster. The probability of any given function being added is the number of samples divided by the number of total pixels.

Rather than storing the indexes of all possible (accessible, not nan) pixels, which is potentially encredibly memory-inefficient for large rasters, it is much better to only store the indexes of roughly the number of total pixels we need to sample. A random number generator is used for each pixel which is a candidate for being added as a sample. The sample is retained if the random number generator creates a series of 1's for the first n bits. This value n determines the probability a sample is added. For example, if n were three then 1/8 or 1/(2^n) pixels would be sampled.

It can be seen that setting up an n value which is close to the probability samples/pixels but an over estimation would result in an adequte number of indexes stored WITHOUT storing a rediculous number of values.

The way this number n is enforced, is by determining a multiplier that takes the form of the first n bits are 1 and the remaining are 0. For example: 1 -> 00000001 -> 50% 3 -> 00000011 -> 25% 7 -> 00000111 -> 12.5% 63 -> 00111111 -> 1.56%

The AND of this multiplier is taken with the rng value, and the result of that and is compared against the multiplier. The 0's from the and remove the unimportant bits, and the 1's enforce the first n values at the beginning.

The multiplier is determined by determining the numerator and denominator of this probability (samples/pixels), with extra multipliers for an unknonwn amount of nan values, and multiplying by extra if the mindist parameter is passed as it may cause samples to be thrown out. Further, if an access vector is given and all samples must fall within the accessible area, the probability is increased by the ratio of the total area in the raster to the accessible area. The probability would then simply be numerator/denominator, but we want a multiplier with a specific number of bits not a small floating point value. The log base 2 is used to transform this division int a subtraction problem, resulting in the number of bits. The value 1 is then left shifted by the number of bits, and subtracted by 1 to give the multiplier.

Parameters

double	width
double	height
double	pixelWidth
double	pixelHeight
int	startMult
int	numSamples
bool	useMindist
double	accessibleArea

Returns: uint64_t

◆ is_valid_sample()

bool sgs::helper::is_valid_sample	(	double	x,
		double	y,
		NeighborMap &	neighbor_map,
		float	mindist,
		float	mindist_sq )

inline

This is the spatial hashing core implementation if a minimum distance is provided.

Parameters

double	x
double	y
NeighborMap&	neighbor_map
float	mindist
float	mindist_sq

◆ point2index()

template<typename T>

T sgs::helper::point2index	(	double	xCoord,
		double	yCoord,
		double *	IGT,
		T	width )

inline

Helper function for calculating the index of a point in a raster. The inverse geotransform is used to calculate the x index and y index. The width is used to calculate a single index assuming row-major.

Parameters

double	xCoord
double	yCoord
double	*IGT
T	width

Returns: int64_t index

◆ printTypeWarningsForInt32Conversion()

void sgs::helper::printTypeWarningsForInt32Conversion ( GDALDataType type )

inline

Helper function which prints a warning to the user if conversion from the raster data type they're using for a strat raster may result in errors in conversion to a 32 bit signed integer type.

Parameters

GDALDataType type

◆ rasterBandIO()

void sgs::helper::rasterBandIO	(	RasterBandMetaData &	band,
		void *	p_buffer,
		int	xBlockSize,
		int	yBlockSize,
		int	xBlock,
		int	yBlock,
		int	xValid,
		int	yValid,
		bool	read,
		bool	threaded = true )

inline

This helper function is used to either read or write a chunk of memory from or to a raster band. If the block size of the band corresponds to the block size of the memory, ReadBlock() or WriteBlock() may be used. Otherwise, RasterIO is used. The boolean parameter 'read' lets the function know whether the band should be read to the buffer, or the buffer should be written to the band.

Parameters

RasterBandMetaData&	band
void	*p_buffer
int	xBlockSize
int	yBlockSize
int	xBlock
int	yBlock
int	xValid
int	yValid
bool	read
bool	threaded

◆ sample_to_point() [1/2]

std::pair< double, double > sgs::helper::sample_to_point	(	double *	GT,
		Index &	index )

inline

Convert a sample into a coordinate pair (x, y) from an Index

Parameters

double*	GT
Index	index

◆ sample_to_point() [2/2]

std::pair< double, double > sgs::helper::sample_to_point	(	double *	GT,
		int	xs,
		int	ys )

inline

Convert a sample into a coordinate pair (x, y) from a x/y index

Parameters

double*	GT
int	xs
int	ys

◆ setStrataPixelDependingOnType()

void sgs::helper::setStrataPixelDependingOnType	(	GDALDataType	type,
		void *	p_data,
		size_t	index,
		bool	isNan,
		size_t	strata )

inline

Helper function for writing a particular pixel value to a strat raster data buffer. The data buffer is cast to the type corresponding to the GDALDataType type parameter. Then, the value at the index provided is set to either 'strata' if isNan is false, or -1 if isNan is true in the type required.

Parameters

GDALDataType	type
void	*p_data
size_t	index
bool	isNan
size_t	strata

◆ setStratBandTypeAndSize()

void sgs::helper::setStratBandTypeAndSize	(	size_t	maxStrata,
		GDALDataType *	p_type,
		size_t *	p_size )

inline

Helper function which determines the smallest signed integer type and it's corresponding size which can fit the maxStrata without overflow errors.

Parameters

size_t	maxStrata
GDALDataType	*p_dtye
size_t	*p_size

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ NeighborMap

Function Documentation

◆ addBandToMEMDataset()

◆ addBandToVRTDataset()

◆ addPoint() [1/6]

◆ addPoint() [2/6]

◆ addPoint() [3/6]

◆ addPoint() [4/6]

◆ addPoint() [5/6]

◆ addPoint() [6/6]

◆ createDataset()

◆ createVirtualDataset()

◆ createVRTBandDataset()

◆ getPixelValueDependingOnType()

◆ getProbabilityMultiplier()

◆ is_valid_sample()

◆ point2index()

◆ printTypeWarningsForInt32Conversion()

◆ rasterBandIO()

◆ sample_to_point() [1/2]

◆ sample_to_point() [2/2]

◆ setStrataPixelDependingOnType()

◆ setStratBandTypeAndSize()