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 raster-bands.
Implementations§
source§impl Dataset
impl Dataset
sourcepub unsafe fn c_dataset(&self) -> GDALDatasetH
pub unsafe fn c_dataset(&self) -> GDALDatasetH
sourcepub fn open<P: AsRef<Path>>(path: P) -> Result<Dataset>
pub fn open<P: AsRef<Path>>(path: P) -> Result<Dataset>
Open a dataset at the given path
with default
options.
sourcepub fn open_ex<P: AsRef<Path>>(
path: P,
options: DatasetOptions<'_>
) -> Result<Dataset>
pub fn open_ex<P: AsRef<Path>>( path: P, options: DatasetOptions<'_> ) -> Result<Dataset>
Open a dataset with extended options. See
GDALOpenEx
.
sourcepub fn flush_cache(&mut self) -> Result<()>
pub fn flush_cache(&mut self) -> Result<()>
Flush all write cached data to disk.
See [GDALFlushCache
].
Note: on GDAL versions older than 3.7, this function always succeeds.
sourcepub fn close(self) -> Result<()>
pub fn close(self) -> Result<()>
Close the dataset.
See [GDALClose
].
Note: on GDAL versions older than 3.7.0, this function always succeeds.
sourcepub unsafe fn from_c_dataset(c_dataset: GDALDatasetH) -> Dataset
pub unsafe fn from_c_dataset(c_dataset: GDALDatasetH) -> Dataset
Creates a new Dataset by wrapping a C pointer
Safety
This method operates on a raw C pointer
The dataset must not have been closed (using [GDALClose
]) before.
sourcepub fn projection(&self) -> String
pub fn projection(&self) -> String
Fetch the projection definition string for this dataset.
sourcepub fn set_projection(&mut self, projection: &str) -> Result<()>
pub fn set_projection(&mut self, projection: &str) -> Result<()>
Set the projection reference string for this dataset.
sourcepub fn spatial_ref(&self) -> Result<SpatialRef>
pub fn spatial_ref(&self) -> Result<SpatialRef>
Get the spatial reference system for this dataset.
sourcepub fn set_spatial_ref(&mut self, spatial_ref: &SpatialRef) -> Result<()>
pub fn set_spatial_ref(&mut self, spatial_ref: &SpatialRef) -> Result<()>
Set the spatial reference system for this dataset.
pub fn create_copy<P: AsRef<Path>>( &self, driver: &Driver, filename: P, options: &[RasterCreationOption<'_>] ) -> Result<Dataset>
sourcepub fn rasterband(&self, band_index: isize) -> Result<RasterBand<'_>>
pub fn rasterband(&self, band_index: isize) -> Result<RasterBand<'_>>
Fetch a band object for a dataset.
Applies to raster datasets, and fetches the rasterband at the given 1-based index.
sourcepub fn root_group(&self) -> Result<Group<'_>>
pub fn root_group(&self) -> Result<Group<'_>>
Opens the root group of a multi-dim GDAL raster
Note
You must have opened the dataset with the GdalOpenFlags::GDAL_OF_MULTIDIM_RASTER
flag in order for it to work.
sourcepub fn build_overviews(
&mut self,
resampling: &str,
overviews: &[i32],
bands: &[i32]
) -> Result<()>
pub fn build_overviews( &mut self, resampling: &str, overviews: &[i32], bands: &[i32] ) -> Result<()>
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
sourcepub fn layer_count(&self) -> isize
pub fn layer_count(&self) -> isize
Get the number of layers in this dataset.
sourcepub fn layer(&self, idx: isize) -> Result<Layer<'_>>
pub fn layer(&self, idx: isize) -> Result<Layer<'_>>
Fetch a layer by index.
Applies to vector datasets, and fetches by the given 0-based index.
sourcepub fn into_layer(self, idx: isize) -> Result<OwnedLayer>
pub fn into_layer(self, idx: isize) -> Result<OwnedLayer>
Fetch a layer by index.
Applies to vector datasets, and fetches by the given 0-based index.
sourcepub fn layer_by_name(&self, name: &str) -> Result<Layer<'_>>
pub fn layer_by_name(&self, name: &str) -> Result<Layer<'_>>
Fetch a layer by name.
sourcepub fn into_layer_by_name(self, name: &str) -> Result<OwnedLayer>
pub fn into_layer_by_name(self, name: &str) -> Result<OwnedLayer>
Fetch a layer by name.
sourcepub fn layers(&self) -> LayerIterator<'_> ⓘ
pub fn layers(&self) -> LayerIterator<'_> ⓘ
Returns an iterator over the layers of the dataset.
sourcepub fn raster_count(&self) -> isize
pub fn raster_count(&self) -> isize
Fetch the number of raster bands on this dataset.
sourcepub fn raster_size(&self) -> (usize, usize)
pub fn raster_size(&self) -> (usize, usize)
Returns the raster dimensions: (width, height).
sourcepub fn create_layer(&mut self, options: LayerOptions<'_>) -> Result<Layer<'_>>
pub fn create_layer(&mut self, options: LayerOptions<'_>) -> Result<Layer<'_>>
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();
sourcepub fn set_geo_transform(&mut self, transformation: &GeoTransform) -> Result<()>
pub fn set_geo_transform(&mut self, transformation: &GeoTransform) -> Result<()>
Set the Dataset
’s affine transformation; also called a geo-transformation.
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
- coefficients of the transformation, which are:- 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)
sourcepub fn geo_transform(&self) -> Result<GeoTransform>
pub fn geo_transform(&self) -> Result<GeoTransform>
Get the coefficients of the Dataset
’s affine transformation.
Returns
- 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)
sourcepub fn start_transaction(&mut self) -> Result<Transaction<'_>>
pub fn start_transaction(&mut self) -> Result<Transaction<'_>>
For datasources which support transactions, this creates a transaction.
Because the transaction implements DerefMut
, it can be used in place of the original
Dataset
to make modifications. 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.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(())
}
sourcepub fn execute_sql<S: AsRef<str>>(
&self,
query: S,
spatial_filter: Option<&Geometry>,
dialect: Dialect
) -> Result<Option<ResultSet<'_>>>
pub fn execute_sql<S: AsRef<str>>( &self, query: S, spatial_filter: Option<&Geometry>, dialect: Dialect ) -> Result<Option<ResultSet<'_>>>
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
query
: The SQL queryspatial_filter
: Limit results of the query to features that intersect the givenGeometry
dialect
: The dialect of SQL to use. See https://gdal.org/user/ogr_sql_sqlite_dialect.html
Example
use gdal::vector::sql;
use gdal::vector::LayerAccess;
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);
}
source§impl Dataset
impl Dataset
sourcepub fn gcp_spatial_ref(&self) -> Option<SpatialRef>
pub fn gcp_spatial_ref(&self) -> Option<SpatialRef>
Get output spatial reference system for GCPs.
Notes
- This is separate and distinct from
Dataset::spatial_ref
, and only applies to the representation of ground control points, when embedded.
See: GDALGetGCPSpatialRef
sourcepub fn gcp_projection(&self) -> Option<String>
pub fn gcp_projection(&self) -> Option<String>
Get the projection definition string for the GCPs in this dataset.
Notes
- This is separate and distinct from
Dataset::projection
, and only applies to embedded GCPs.
See: GDALGetGCPProjection
sourcepub fn gcps(&self) -> &[GcpRef<'_>]
pub fn gcps(&self) -> &[GcpRef<'_>]
Fetch GCPs.
See: GDALDataset::GetGCPs
sourcepub fn set_gcps(&self, gcps: Vec<Gcp>, spatial_ref: &SpatialRef) -> Result<()>
pub fn set_gcps(&self, gcps: Vec<Gcp>, spatial_ref: &SpatialRef) -> Result<()>
Assign GCPs.
This method assigns the passed set of GCPs to this dataset, as well as setting their coordinate system.
See: GDALDataset::SetGCPs(int, const GDAL_GCP *, const OGRSpatialReference *)
Panics
Panics if gcps
has more than libc::c_int::MAX
elements.
Trait Implementations§
source§impl From<Dataset> for MultiDimTranslateDestination
impl From<Dataset> for MultiDimTranslateDestination
source§impl From<OwnedLayer> for Dataset
impl From<OwnedLayer> for Dataset
source§fn from(owned_layer: OwnedLayer) -> Self
fn from(owned_layer: OwnedLayer) -> Self
source§impl Metadata for Dataset
impl Metadata for Dataset
source§fn description(&self) -> Result<String>
fn description(&self) -> Result<String>
crate::Dataset
s, method returns this is the originating filename.
For crate::raster::RasterBand
s it is a description (if supported) or ""
. Read moresource§fn metadata_domains(&self) -> Vec<String>
fn metadata_domains(&self) -> Vec<String>
""
).
Specific “Major Object” types may have other conventionally recognized domains.
For example, in raster Dataset
s you may come across the domains
SUBDATASETS
, IMAGE_STRUCTURE
, RPC
, IMAGERY
, xml:
, etc. Read moresource§fn metadata_domain(&self, domain: &str) -> Option<Vec<String>>
fn metadata_domain(&self, domain: &str) -> Option<Vec<String>>
domain
. Returns None
if
domain is not defined.
Entries in the returned Vec<String>
are formatted as “Name=value” pairs Read more