This page has been translated automatically.
Программирование
Fundamentals
Setting Up Development Environment
UnigineScript
High-Level Systems
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes
Внимание! Эта версия документация УСТАРЕЛА, поскольку относится к более ранней версии SDK! Пожалуйста, переключитесь на самую актуальную документацию для последней версии SDK.
Внимание! Эта версия документации описывает устаревшую версию SDK, которая больше не поддерживается! Пожалуйста, обновитесь до последней версии SDK.

Unigine::Dataset Class

Header:#include <UnigineDataset.h>

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.

Notice
The .ecw format will be loaded only if you install the ECW plugin and accept the ECW EULA.

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:

Source code (C++)
// 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");
	// desclare 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

A vector dataset is a set of layers, each of which contains meta-information (field definitions) and data (features).

Field definitions is a set of names that can be assotiated with the application logic. For example, the name "height" allows assuming that the feature will contain information on heights, so you can make geometry three-dimensional in yor application.

Features contain of geometry and field values that are assotiated with field definitions. If a layer of vector dataset contains several features, they will be read from the source successively. The memory contains only the currently read feature that is processed.

Geometry can be simple (a point, line, polygon) and complex (a set of points, lines or polygon). In the Dataset class, working with geometry is similar to working with a Unigine mesh: you can get the number of "surfaces" (geometries) and points of one of such "surfaces" (geometries). For the simple geometry, there is a single "surface". For the complex one, there are several "sufaces".

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

Source code (C++)
// 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 assotiated 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 assotiated 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()

Constructor. Creates a new dataset.

const char * getCreationData()

Returns a list of space separated data types supported by the format of the dataset.

Return value

Dataset format data types.

const char * getCreationOption()

Returns options specified for the format of the dataset.

Return value

Dataset format opitons.

const char * getDescription()

Returns the description of the format of the dataset.

Return value

Dataset format description.

void getGeodeticPosition(int x, int y, double & latitude, double & longitude)

Transforms the given raster position to geodetic position (WGS84).

Arguments

  • int x - X coordinate of the pixel.
  • int y - Y coordinate of the pixel.
  • double & latitude - North-south position in degrees.
  • double & longitude - East-west position in degrees.

double getLatitude(int x, int y)

Returns the north–south position of the given raster position.

Arguments

  • int x - X coordinate of the pixel.
  • int y - Y coordinate of the pixel.

Return value

The north-south position in degrees.

double getLongitude(int x, int y)

Returns the east-west position of the given raster position.

Arguments

  • int x - X coordinate of the pixel.
  • int y - Y coordinate of the pixel.

Return value

The east-west position in degrees.

double getOriginX()

Returns the north-south position of the pixel in the top left corner.

Return value

North-south position in degrees.

double getOriginY()

Returns the east-west position of the pixel in the top left corner.

Return value

East-west position in degrees.

const char * getProjection()

Returns a string that defines the projection coordinate system of the image in OpenGIS WKT format.

Return value

String with the projection coordinate system.

const char * getRasterColorName(int num)

Returns the name of color representation for the given raster band of the dataset.

Arguments

  • int num - Raster band number.

Return value

Name of color representation.

int getRasterCount()

Returns the number of raster bands in the dataset.

Return value

Number of raster bands.

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

Writes the region of the raster band with the specified offsets into the given image. The size of the region corresponds to the size of the given image. If the raster band less that the image, the whole raster band will be written.
Notice
Only R8, R16, R32F types of the pixel values of the raster band are supported.

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.

Return value

1 if the region has been read successfully; otherwise, 0.

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

Writes the regions of all the raster band with the specified offsets into the given images. The size of the region corresponds to the size of the given image. If the raster band size less that the image size, the whole raster band will be written. The function processes only 3 or 4 raster bands (an image must be of theRGB format for 3 bands or the RGBA format for 4 bands).
Notice
Only RGB8, RGB16, RGB32F, RGBA8, RGBA16, RGBA32F types of the pixel values of the raster bands are supported. Pixels of all the raster bands must be of the same type.

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.

Return value

1 if the regions have been read successfully; otherwise, 0.

double getRasterMaximumValue(int num)

Returns the maximum value for the specified raster band of the dataset.

Arguments

  • int num - Raster band number.

Return value

Maximum raster value.

double getRasterMinimumValue(int num)

Returns the minimum value for the specified raster band of the dataset.

Arguments

  • int num - Raster band number.

Return value

Minimum raster value.

double getRasterNoDataValue(int num)

Returns the no data value for the specified raster band of the dataset. The no data value for a band is a special marker value used to mark pixels that are not valid data. Such pixels should generally not be displayed, nor contribute to analysis operations.

Arguments

  • int num - Raster band number.

Return value

No data value.

double getRasterOffset(int num)

Returs the value offset for the specified raster band of the dataset.

Arguments

  • int num - Raster band number.

Return value

Raster value offset.

int getRasterPosition(double latitude, double longitude, int & x, int & y)

Transforms the given geodetic position (WGS84) to the raster position.

Arguments

  • double latitude - North-south position in degrees.
  • double longitude - East-west position in degrees.
  • int & x - X coordinate of the pixel.
  • int & y - Y coordinate of the pixel.

Return value

1 if the transformed pixel is in the raster band (x in range [0;raster_size_x]; y in range [0;raster_size_y]); otherwise, 0.

int getRasterPosition(double latitude, double longitude, float & x, float & y)

Transforms the given geodetic position (WGS84) to the raster position.

Arguments

  • double latitude - North-south position in degrees.
  • double longitude - East-west position in degrees.
  • float & x - X coordinate of the pixel.
  • float & y - Y coordinate of the pixel.

Return value

1 if if the transformed pixel is in the raster band (x in range [0;raster_size_x]; y in range [0;raster_size_y]); otherwise, 0.

void getRasterPositions(double * latitudes, double * longitude, int size, float * ret_x, float * ret_y, bool * ret_pixels)

Transforms the given geodetic positions (WGS84) to the raster positions. The size of the array of input geodetic positions must be equal to the size of output raster positions.

Arguments

  • double * latitudes - Array of north-south positions in degrees.
  • double * longitude - Array of east-west positions in degrees.
  • int size - Size of array of geodetic positions.
  • float * ret_x - Array of X coordinates of pixels.
  • float * ret_y - Array of Y coordinates of pixels.
  • bool * ret_pixels - Array of values indicating if the transformed pixels are in the raster band: 1 if the pixel is in the raster band (x in range [0;raster_size_x]; y in range [0;raster_size_y]); otherwise, 0.

void getRasterPositions(double * latitudes, double * longitude, int size, int * ret_x, int * ret_y, bool * ret_pixels)

Transforms the given geodetic positions (WGS84) to the raster positions. The size of the array of input geodetic positions must be equal to the size of output raster positions.

Arguments

  • double * latitudes - Array of north-south positions in degrees.
  • double * longitude - Array of east-west positions in degrees.
  • int size - Size of array of geodetic positions.
  • int * ret_x - Array of X coordinates of pixels.
  • int * ret_y - Array of Y coordinates of pixels.
  • bool * ret_pixels - Array of values indicating if the transformed pixels are in the raster band: 1 if the pixel is in the raster band (x in range [0;raster_size_x]; y in range [0;raster_size_y]); otherwise, 0.

double getRasterScale(int num)

Returns the scale value for the given raster band of the dataset.

Arguments

  • int num - Raster band number.

Return value

Raster scale.

int getRasterSizeX()

Returns the width of raster bands of the dataset.

Return value

Raster width in pixels.

int getRasterSizeY()

Returns the height of raster bands of the dataset.

Return value

Raster height in pixels.

const char * getRasterTypeName(int num)

Returns the name for the data type of the specified raster band of the dataset.

Arguments

  • int num - Raster band number.

Return value

Name of the data type.

const char * getRasterUnitType(int num)

Returns the name of the units of the raster band values.

Arguments

  • int num - Raster band number.

Return value

Name of the units.

double getResolutionX()

Returns resolution of the east-west pixel (i.e. width of the pixel).

Return value

East-west pixel resolution.

double getResolutionY()

Returns resolution of the north-south pixel (i.e. height of the pixel).

Return value

North-south pixel resolution.

int getVectorCount()

Returns the number of layers in the vector dataset.

Return value

Number of layers in the vector dataset.

int getVectorFieldCount(int num)

Returns the number of field definitions in the given layer of the vector dataset.

Arguments

  • int num - Layer index in the vector dataset.

Return value

Number of layer field definitions.

const char * getVectorFieldName(int num, int field)

Returns the name of the given field definition of the current feature of the given layer.

Arguments

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

Return value

Field definition name.

Variable getVectorFieldValue(int num, int field)

Returns the value of the given field definition of the current feature of the given layer.

Arguments

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

Return value

Field value.

const char * getVectorName(int num)

Returns the name of the given layer of the vector dataset.

Arguments

  • int num - Layer index in the vector dataset.

Return value

Name of the layer.

int getVectorSurfaceCount(int num)

Returns the number of surfaces of the current feature in the given Layer.

Arguments

  • int num - Layer index in the vector dataset.

Return value

Number of surfaces.

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

Returns coordinates of the surface point in the current feature of the given layer.

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

Surface point coordinates.

int getVectorSurfacePointCount(int num, int surface)

Returns the number of surface points in the current feature of the given layer.

Arguments

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

Return value

Number of surface points.

void clear()

Clears the dataset.

int load(const char * name)

Loads the given dataset.

Arguments

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

Return value

1 if dataset has been loaded successfully; otherwise, 0.

int vectorFeatureReadNext(int num)

Reads the next available feature from the given layer.

Arguments

  • int num - Layer index in vector dataset.

Return value

1 if the feature exists; otherwise, 0.

void vectorFeatureReadReset(int num)

Resets feature reading to start on the first feature.

Arguments

  • int num - Layer index in vector dataset.
Last update: 03.07.2017
Build: ()