Unigine::Dataset Class

The Dataset class is used for processing raster and vector data with binding to geo-coordinates. The class uses GDAL API to retrieve data from files.

The class allows for loading such rare raster formats as .dem, .tiff (with information on binding to geo-coordinates), .ecw and vector formats .osm, .shp.

For raster data, geo-coordinates can be obtained per-pixel in the (latitude, longitude) format. Pixel values can be of different formats (R8, R16, R32F for single-channel data; RGB8, RGB16, RGB32F, RGBA8, RGBA16, RGBA32F for multi-channel data).

The following example shows how raster data can be accessed by using methods of the Dataset class:

// AppWorldLogic.cpp

#include <UnigineDataset.h>
#include <UnigineLog.h>
#include <UnigineEngine.h>
#include <UnigineImage.h>
#include <UnigineInterface.h>

int AppWorldLogic::init() {
	
	// create a new dataset
	DatasetPtr dataset = Dataset::create();
	// load raster data
	dataset->load("unigine_project/maps/geo.tif");
	// declare images into which raster data obtained from the loaded dataset will be saved
	Vector<ImagePtr> raster_data;
	// print data on each raster band of the dataset
	for (int i = 0; i < dataset->getRasterCount(); i++) {
		Log::message("Band:  %d\n", i);
		Log::message("Type:  %s\n", dataset->getRasterTypeName(i));
		Log::message("Color: %s\n", dataset->getRasterColorName(i));

		ImagePtr image = Image::create();
		// create an image of the size and format of the current raster band
		image->create2D(dataset->getRasterSizeX(), dataset->getRasterSizeY(), Image::FORMAT_R8);
		// read the region of the current raster band into the created image
		if (dataset->getRasterImage(i, image) == 0) {			
			Log::error("Can't import raster band, layer: %d\n", i);
			continue;
		}
		// add the obtained raster data to the array
		raster_data.append(image);
	}

	for (int y = 0; y < dataset->getRasterSizeY(); y += dataset->getRasterSizeY() - 1) {
		for (int x = 0; x < dataset->getRasterSizeX(); x += dataset->getRasterSizeX() - 1) {
			double latitude = dataset->getLatitude(x, y);
			double longitude = dataset->getLongitude(x, y);
			Log::message("%4dx%-4d: %f / %f\n", x, y, latitude, longitude);
		}
	}
	
	return 1;
}

For vector data, the number of primitives, their points and properties can be obtained. You can also triangulate a primitive and save it to a dynamic mesh (see the samples_2/geodetics/dataset_00 sample).

Vector Dataset

// AppWorldLogic.cpp

#include <UnigineDataset.h>
#include <UnigineLog.h>
#include <UnigineEngine.h>
#include <UnigineInterface.h>

using namespace Unigine; 

int AppWorldLogic::init() {
	// create a new dataset
	DatasetPtr dataset = Dataset::create();
	// load vector data
	dataset->load("unigine_project/maps/antarctica.shp");
	// print information on the dataset layers
	for (int i = 0; i < dataset->getVectorCount(); i++) {
		Log::message("Layer:  %d\n", i);
		Log::message("Name:   %s\n", dataset->getVectorName(i));
		Log::message("Fields: %d\n", dataset->getVectorFieldCount(i));
		Log::message("Features:\n");
		// print field definitions and its associated values for each feature of the dataset layer
		// starting from the first feature
		dataset->vectorFeatureReadReset(i);
		// obtain the current feature
		while (dataset->vectorFeatureReadNext(i)) {
			// for each field definition of the current feature
			for (int j = 0; j < dataset->getVectorFieldCount(i); j++) {
				// get the name
				const char *field_name = dataset->getVectorFieldName(i, j);
				// get the associated value
				Variable field_value = dataset->getVectorFieldValue(i, j);
				// print the obtained values
				Log::message("\t%s: %s\n", field_name, field_value.getTypeInfo().get());
			}
		}
	}
	
	return 1;
}

Dataset Class

Members

static DatasetPtr create()

const char * getCreationData()

Return value

const char * getCreationOption()

Return value

const char * getDescription()

Return value

int isOwner()

Return value

const char * getProjection()

Return value

Vector< int > getRasterBandHistogramm(int num, double v_min, double v_max, int num_buckets)

Arguments

• int num - Raster band number.
• double v_min - Lower bound of the histogram.
• double v_max - Upper bound of the histogram.
• int num_buckets - Number of buckets in the histogram.

Return value

const char * getRasterColorName(int num)

Arguments

• int num - Raster band number.

Return value

int getRasterCount()

Return value

int getRasterImage(int num, const Ptr<Image> & image, int offset_x = 0, int offset_y = 0, int scale = 1)

Arguments

• int num - Raster band number.
• const Ptr<Image> & image - Image into which the raster band should be read.
• int offset_x - Pixel offset to the top left corner of the region of the band to be written. To start from the left, 0 should be specified.
• int offset_y - Line offset to the top left corner of the region of the band to be written. To start from the top, 0 should be specified.
• int scale - Scale factor.

Return value

int getRasterImageAllBands(const Ptr<Image> & image, int offset_x = 0, int offset_y = 0, int scale = 1)

Arguments

• const Ptr<Image> & image - Image into which the raster bands should be read.
• int offset_x - Pixel offset to the top left corner of the region of the band to be accessed. To start from the left, 0 should be specified.
• int offset_y - Line offset to the top left corner of the region of the band to be accessed. To start from the top, 0 should be specified.
• int scale - Scale factor.

Return value

double getRasterMaximumValue(int num)

Arguments

• int num - Raster band number.

Return value

double getRasterMinimumValue(int num)

Arguments

• int num - Raster band number.

Return value

double getRasterNoDataValue(int num)

Arguments

• int num - Raster band number.

Return value

double getRasterOffset(int num)

Arguments

• int num - Raster band number.

Return value

Ptr<DatasetRasterPosResolver> getRasterPosResolver()

Return value

double getRasterScale(int num)

Arguments

• int num - Raster band number.

Return value

int getRasterSizeX()

Return value

int getRasterSizeY()

Return value

const char * getRasterTypeName(int num)

Arguments

• int num - Raster band number.

Return value

const char * getRasterUnitType(int num)

Arguments

• int num - Raster band number.

Return value

int setVectorAttributeFilter(int num, const char * filter)

This method sets the attribute query string to be used when fetching features via the vectorFeatureReadNext() method. Only features for which the query evaluates as true will be returned.

The query string should be in the format of an SQL WHERE clause. For instance: "population > 1000000 and population < 5000000", where population is an attribute in the layer. The query format is normally a restricted form of SQL WHERE clause. In some cases (RDBMS backed drivers) the native capabilities of the database may be used to interpret the WHERE clause in which case the capabilities will be broader than those of OGR SQL.

Arguments

• int num - Layer index in the vector dataset.
• const char * filter - Query in restricted SQL WHERE format, or NULL to clear the current query.

Return value

int getVectorCount()

Return value

int getVectorFieldCount(int num)

Arguments

• int num - Layer index in the vector dataset.

Return value

int findVectorField(int num, const char * name)

Arguments

• int num - Layer index in the vector dataset.
• const char * name - Field definition name.

Return value

const char * getVectorFieldName(int num, int field)

Arguments

• int num - Layer index in the vector dataset.
• int field - Field definition index.

Return value

int getVectorFieldType(int num, int field)

Arguments

• int num - Layer index in the vector dataset.
• int field - Field definition index.

Return value

Variable getVectorFieldValue(int num, int field)

Arguments

• int num - Layer index in the vector dataset.
• int field - Field definition index.

Return value

const char * getVectorName(int num)

Arguments

• int num - Layer index in the vector dataset.

Return value

void setVectorSpatialFilter(int num, const Math::dvec3 & min_val, const Math::dvec3 & max_val)

Arguments

• int num - Layer index in the vector dataset.
• const Math::dvec3 & min_val - Start coordinates of the bounding box.
• const Math::dvec3 & max_val - End coordinates for the bounding box.

int getVectorSurfaceCount(int num)

Arguments

• int num - Layer index in the vector dataset.

Return value

Math::dvec3 getVectorSurfacePoint(int num, int surface, int point)

Arguments

• int num - Layer index in vector dataset.
• int surface - Surface index from which to get point coordinates.
• int point - Surface point index.

Return value

int getVectorSurfacePointCount(int num, int surface)

Arguments

• int num - Layer index in vector dataset.
• int surface - Surface index from which to get points.

Return value

Vector< Math::dvec3 > getVectorSurfacePoints(int num, int surface)

Arguments

• int num - Layer index in vector dataset.
• int surface - Surface index from which to get points.

Return value

int calcVectorBounds(Math::dvec3 & min_val, Math::dvec3 & max_val)

Arguments

• Math::dvec3 & min_val
• Math::dvec3 & max_val

void clear()

void clearVectorSpatialFilter(int num)

Arguments

• int num - Layer index in vector dataset.

void grab()

int hasRasterRGBColorTable(int num)

Arguments

• int num - Band number.

Return value

int load(const char * name)

Arguments

• const char * name - Dataset name (a path to a file with raster or vector data).

Return value

void release()

int vectorFeatureReadNext(int num)

Arguments

• int num - Layer index in vector dataset.

Return value

void vectorFeatureReadReset(int num)

Arguments

• int num - Layer index in vector dataset.

int rasterizeIntoMask(int num, const char * output_path, const Vector< String > & filters, int width, int height)

Arguments

• int num - Layer index in vector dataset.
• const char * output_path - Path to which the rasterized vector dataset layer is to be saved.
• const Vector< String > & filters -

  Queries in restricted SQL WHERE clause format to be evaluated against the datasource to produce a virtual layer of features to be rasterized. For instance: "population > 1000000 and population < 5000000", where population is an attribute in the layer.

  Each filter is represented by a separate raster band.

  Notice

  The maximum supported number of filters is 4.
• int width - Output raster mask width, in pixels.
• int height - Output raster mask height, in pixels.

Return value