open
Prototype
template<class T>
gdal_raster_view<T> open(const filesystem::path& path, access elem_access = read_write, int band_index = 1);
Description
Opens a GDALDataset
using the GDAL library and ties one raster band from the dataset to a new gdal_raster_view
object. The user does not need to be concerned about closing the GDALDataset
or GDALRasterBand
. It will be closed when the gdal_raster_view
or is deleted / goes out of scope.
The template parameter T
is the value_type to which values of cells in the GDALRasterBand
are cast. This does not necessarily correspond to the data type as present in the raster band.
elem_access
specifies the access type, it is either read_only
or read_write
.
band_index
specifies which band from the dataset to open. The index is 1-based, so the first raster band has index 1.
Definition
<pronto/raster/io.h> (open in Github)
Requirements on types
The type of the raster dataset must be castable to T
Preconditions
path must refer to an existing raster dataset that can be read by the GDAL library. band_index must be greater than zero (the bands are numbered starting from 1). the raster dataset must at least have the number of bands corresponding to band_index.
Complexity
The cost of the operation is governed by the filesystem that has to open the tiff file and read metadata. On opening it is not necessary to read the raster data itself.
Example of use
//example_open.cpp
#include <pronto/raster/io.h>
#include <pronto/raster/plot_raster.h>
namespace pr = pronto::raster;
int main()
{
{
auto raster = pr::create<int>("test.tif", 3, 4, GDT_Byte);
}
auto opened_raster = pr::open<short>("test.tif");
int i = 0;
for (auto&& v : opened_raster) {
i = (i + 3) % 7;
v = i;
}
plot_raster(opened_raster);
return 0;
}
Output:
Rows: 3, Cols: 4.
3 6 2 5
1 4 0 3
6 2 5 1
Notes
Note that these function open a GDALDataset for the given path, and there are some limitations to opening GDALDatasets. In particular, if you open a dataset object with read_write access, it is not recommended to open a new dataset on the same underlying file. The opened dataset, and hence the gdal_raster_view should only be accessed by one thread at a time. If you want to use it from different threads, you must add all necessary code (mutexes, etc.) to avoid concurrent use of the object.