Struct Dataset

Source
pub struct Dataset { /* private fields */ }
Expand description

Wrapper around a GDALDataset object.

Represents both a vector dataset containing a collection of layers; and a raster dataset containing a collection of rasterbands.

Implementations§

Source§

impl Dataset

Source

pub unsafe fn c_dataset(&self) -> *mut c_void

Returns the wrapped C pointer

§Safety

This method returns a raw C pointer

Source

pub fn open<P>(path: P) -> Result<Dataset, GdalError>
where P: AsRef<Path>,

Open a dataset at the given path with default options.

Source

pub fn open_ex<P>( path: P, options: DatasetOptions<'_>, ) -> Result<Dataset, GdalError>
where P: AsRef<Path>,

Open a dataset with extended options. See GDALOpenEx.

Source

pub unsafe fn from_c_dataset(c_dataset: *mut c_void) -> Dataset

Creates a new Dataset by wrapping a C pointer

§Safety

This method operates on a raw C pointer

Source

pub fn projection(&self) -> String

Fetch the projection definition string for this dataset.

Source

pub fn set_projection(&mut self, projection: &str) -> Result<(), GdalError>

Set the projection reference string for this dataset.

Source

pub fn spatial_ref(&self) -> Result<SpatialRef, GdalError>

Get the spatial reference system for this dataset.

Source

pub fn set_spatial_ref( &mut self, spatial_ref: &SpatialRef, ) -> Result<(), GdalError>

Set the spatial reference system for this dataset.

Source

pub fn create_copy<P>( &self, driver: &Driver, filename: P, options: &[RasterCreationOption<'_>], ) -> Result<Dataset, GdalError>
where P: AsRef<Path>,

Source

pub fn driver(&self) -> Driver

Fetch the driver to which this dataset relates.

Source

pub fn rasterband(&self, band_index: isize) -> Result<RasterBand<'_>, GdalError>

Fetch a band object for a dataset.

Applies to raster datasets, and fetches the rasterband at the given 1-based index.

Source

pub fn build_overviews( &mut self, resampling: &str, overviews: &[i32], bands: &[i32], ) -> Result<(), GdalError>

Builds overviews for the current Dataset. See GDALBuildOverviews.

§Arguments
  • resampling - resampling method, as accepted by GDAL, e.g. "CUBIC"
  • overviews - list of overview decimation factors, e.g. &[2, 4, 8, 16, 32]
  • bands - list of bands to build the overviews for, or empty for all bands
Source

pub fn layer_count(&self) -> isize

Get the number of layers in this dataset.

Source

pub fn layer(&self, idx: isize) -> Result<Layer<'_>, GdalError>

Fetch a layer by index.

Applies to vector datasets, and fetches by the given 0-based index.

Source

pub fn layer_by_name(&self, name: &str) -> Result<Layer<'_>, GdalError>

Fetch a layer by name.

Source

pub fn layers(&self) -> LayerIterator<'_>

Returns an iterator over the layers of the dataset.

Source

pub fn raster_count(&self) -> isize

Fetch the number of raster bands on this dataset.

Source

pub fn raster_size(&self) -> (usize, usize)

Returns the raster dimensions: (width, height).

Source

pub fn create_layer<'a>( &mut self, options: LayerOptions<'a>, ) -> Result<Layer<'_>, GdalError>

Creates a new layer. The LayerOptions struct implements Default, so you only need to specify those options that deviate from the default.

§Examples

Create a new layer with an empty name, no spatial reference, and unknown geometry type:

let blank_layer = dataset.create_layer(Default::default()).unwrap();

Create a new named line string layer using WGS84:

let roads = dataset.create_layer(LayerOptions {
    name: "roads",
    srs: Some(&SpatialRef::from_epsg(4326).unwrap()),
    ty: gdal_sys::OGRwkbGeometryType::wkbLineString,
    ..Default::default()
}).unwrap();
Source

pub fn set_geo_transform( &mut self, transformation: &[f64; 6], ) -> Result<(), GdalError>

Affine transformation called geotransformation.

This is like a linear transformation preserves points, straight lines and planes. Also, sets of parallel lines remain parallel after an affine transformation.

§Arguments
  • transformation - coeficients of transformations

x-coordinate of the top-left corner pixel (x-offset) width of a pixel (x-resolution) row rotation (typically zero) y-coordinate of the top-left corner pixel column rotation (typically zero) height of a pixel (y-resolution, typically negative)

Source

pub fn geo_transform(&self) -> Result<[f64; 6], GdalError>

Get affine transformation coefficients.

x-coordinate of the top-left corner pixel (x-offset) width of a pixel (x-resolution) row rotation (typically zero) y-coordinate of the top-left corner pixel column rotation (typically zero) height of a pixel (y-resolution, typically negative)

Source

pub fn start_transaction(&mut self) -> Result<Transaction<'_>, GdalError>

For datasources which support transactions, this creates a transaction.

During the transaction, the dataset can be mutably borrowed using Transaction::dataset_mut to make changes. All changes done after the start of the transaction are applied to the datasource when commit is called. They may be canceled by calling rollback instead, or by dropping the Transaction without calling commit.

Depending on the driver, using a transaction can give a huge performance improvement when creating a lot of geometry at once. This is because the driver doesn’t need to commit every feature to disk individually.

If starting the transaction fails, this function will return OGRErr::OGRERR_FAILURE. For datasources that do not support transactions, this function will always return OGRErr::OGRERR_UNSUPPORTED_OPERATION.

Limitations:

  • Datasources which do not support efficient transactions natively may use less efficient emulation of transactions instead; as of GDAL 3.1, this only applies to the closed-source FileGDB driver, which (unlike OpenFileGDB) is not available in a GDAL build by default.

  • At the time of writing, transactions only apply on vector layers.

  • Nested transactions are not supported.

  • If an error occurs after a successful start_transaction, the whole transaction may or may not be implicitly canceled, depending on the driver. For example, the PG driver will cancel it, but the SQLite and GPKG drivers will not.

Example:

fn create_point_grid(dataset: &mut Dataset) -> gdal::errors::Result<()> {
    use gdal::vector::Geometry;

    // Start the transaction.
    let mut txn = dataset.start_transaction()?;

    let mut layer = txn.dataset_mut().create_layer(LayerOptions {
        name: "grid",
        ty: gdal_sys::OGRwkbGeometryType::wkbPoint,
        ..Default::default()
    })?;
    for y in 0..100 {
        for x in 0..100 {
            let wkt = format!("POINT ({} {})", x, y);
            layer.create_feature(Geometry::from_wkt(&wkt)?)?;
        }
    }

    // We got through without errors. Commit the transaction and return.
    txn.commit()?;
    Ok(())
}
Source

pub fn execute_sql<S>( &self, query: S, spatial_filter: Option<&Geometry>, dialect: Dialect, ) -> Result<Option<ResultSet<'_>>, GdalError>
where S: AsRef<str>,

Execute a SQL query against the Dataset. It is equivalent to calling GDALDatasetExecuteSQL. Returns a sql::ResultSet, which can be treated just as any other Layer.

Queries such as ALTER TABLE, CREATE INDEX, etc. have no sql::ResultSet, and return None, which is distinct from an empty sql::ResultSet.

§Arguments
§Example
use gdal::vector::sql;

let ds = Dataset::open(Path::new("fixtures/roads.geojson")).unwrap();
let query = "SELECT kind, is_bridge, highway FROM roads WHERE highway = 'pedestrian'";
let mut result_set = ds.execute_sql(query, None, sql::Dialect::DEFAULT).unwrap().unwrap();

assert_eq!(10, result_set.feature_count());

for feature in result_set.features() {
    let highway = feature
        .field("highway")
        .unwrap()
        .unwrap()
        .into_string()
        .unwrap();

    assert_eq!("pedestrian", highway);
}

Trait Implementations§

Source§

impl Debug for Dataset

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
Source§

impl Drop for Dataset

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

impl Metadata for Dataset

Source§

fn description(&self) -> Result<String, GdalError>

Source§

fn metadata_domains(&self) -> Vec<String>

Source§

fn metadata_domain(&self, domain: &str) -> Option<Vec<String>>

Source§

fn metadata_item(&self, key: &str, domain: &str) -> Option<String>

Source§

fn set_metadata_item( &mut self, key: &str, value: &str, domain: &str, ) -> Result<(), GdalError>

Source§

fn set_description(&mut self, description: &str) -> Result<(), GdalError>

Source§

impl Send for Dataset

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<S, D, Swp, Dwp, T> AdaptInto<D, Swp, Dwp, T> for S
where T: FloatComponent, Swp: WhitePoint, Dwp: WhitePoint, D: AdaptFrom<S, Swp, Dwp, T>,

Source§

fn adapt_into_using<M>(self, method: M) -> D
where M: TransformMatrix<Swp, Dwp, T>,

Convert the source color to the destination color using the specified method
Source§

fn adapt_into(self) -> D

Convert the source color to the destination color using the bradford method by default
Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> IntoColor<U> for T
where U: FromColor<T>,

Source§

fn into_color(self) -> U

Convert into T with values clamped to the color defined bounds Read more
Source§

impl<T, U> IntoColorUnclamped<U> for T
where U: FromColorUnclamped<T>,

Source§

fn into_color_unclamped(self) -> U

Convert into T. The resulting color might be invalid in its color space Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T, U> TryIntoColor<U> for T
where U: TryFromColor<T>,

Source§

fn try_into_color(self) -> Result<U, OutOfBounds<U>>

Convert into T, returning ok if the color is inside of its defined range, otherwise an OutOfBounds error is returned which contains the unclamped color. Read more