Introduction¶
This section outlines the general usage of the Python bindings for a VRS
.
All the examples assume the import has been done.
from caris.coverage import *
import numpy
Checking the type of a dataset¶
You can use caris.coverage.identify()
to determine the type of dataset a file contains.
from caris.coverage import *
file_path = r'C:\bathymetry.csar'
type = identify(file_path)
if type == DatasetType.RASTER:
raster = Raster(file_path)
elif type == DatasetType.CLOUD:
cloud = Cloud(file_path)
elif type == DatasetType.VRS:
vrs = VRS(file_path)
Opening a VRS¶
vrs = VRS('source_vrs.csar')
One can specify the named parameter.
vrs = VRS(filename='source_vrs.csar')
One can also supply a URI
vrs = VRS(uri='file:///source_vrs.csar')
Alternatively, the caris.open()
function can be used:
from caris.coverage import *
import caris
# open file read only
vrs = caris.open(file_name='vrs.csar')
# open file read write
vrs = caris.open(file_name='vrs.csar', open_mode=caris.OpenMode.READ_WRITE)
Opening from BDB Server¶
To open a database surface, a URI must be given formatted as:
bdb://username:password@hostname/database/boid
Note
The database name is case sensitive.
Boids (object IDs for database objects) can be found by via caris.bathy.db.DatabaseFeature.id
.
In BASE Editor the boid can be found by selecting a surfac, the boid will be shown in the Selection window. The URI for opened rasters, clouds, or variable resolution surfaces is shown in the Properties window’s “Surface Name” field.
vrs = caris.coverage.VRS(uri='bdb://dba:sql@example.com/MyDB/02000001')
Listing Bands¶
The band information is found in the VRS.band_info
property. It is simply a dictionary where the key is the band name and the value is an instance of BandInfo
.
The band information contains properties such as its type, category, minimum, maximum, no-data-value, etc.
See BandInfo
for more info.
vrs = VRS('source_vrs.csar')
for band_name in vrs.band_info:
print(str(vrs.band_info[band_name]))
Reading from a VRS¶
Reading points from a VRS can be done similar to Cloud with query()
and query_box()
:
vrs = VRS('source_vrs.csar')
points = {}
# Read the points
for band_name in vrs.band_info:
points[band_name] = []
for block in vrs.query():
for pt in block[band_name]:
points[band_name].append(pt)
A VRS stores resolution information in VRSTile
. This can be iterated by calling tiles()
. The points in a tile can be retrieved with query_tile()
, or gridded using VRSGridder
.
vrs = VRS('source_vrs.csar')
gridder = VRSGridder(vrs)
for tile in vrs.tiles():
# Iterate all the points in the tile
blocks = vrs.query_tile(tile)
# Or generate a grid
gridder.load(tile)
grid = gridder.read("Depth")
Querying a VRS¶
A filter can be applied when reading from a VRS
with it’s member function VRS.query
. It can be filtered by band and/or a geographical box.
vrs = VRS('vrs.csar')
# filter by bands
bands = [ 'XYZ']
for block in vrs.query(bands = bands):
xyz_data = block['XYZ']
# do something
# filter by box
query_box = ((3.841061, 51.344868), (3.844457, 51.346305))
for block in vrs.query(box = query_box):
for band in block:
for pt in block[band]:
xyz_data = block['XY']
# do something
# filter by both
for block in vrs.query(bands = bands, box = query_box):
xyz_data = block['XYZ']
# do something
Copying a VRS¶
The simplest way to copy a vrs is to call it’s member function VRS.create_copy
.
vrs = vrs('source_vrs.csar')
outputFilename = 'dest_vrs.csar'
vrs.create_copy(outputFileName)
Updating VRS data¶
VRS data can be updated while iterating through the blocks of data. This can be done by calling BlockIterator.write
during iteration. The numpy array that is passed to it must have the appropriate shape and data type for the band and block being updated.
Note
New data cannot be inserted into an existing VRS.
opts = Options(open_type = OpenType.WRITE)
vrs = VRS('vrs.csar', options = opts)
band_name = 'SomeBand'
bands = [band_name]
query_box = ((3.841061, 51.344868), (3.844457, 51.346305))
itr = vrs.query(bands = bands, box = query_box)
# update blocks
for block in itr:
array = block[band_name]
for i in range(0, array.shape[0]):
array[i] = 1
itr.write(band_name, array)
Updating bounding polygon¶
A bounding polygon can be automatically generated for a VRS. Any valid polygon can be set to be used as the bounding polygon. Used together, a bounding polygon can be replaced with the automatically generated bounding polygon.
opts = Options()
opts.open_type = OpenType.WRITE
variable_resolution_surface = VRS(file_path, options=opts)
new_bounding_polygon = generate_polygon(variable_resolution_surface)
variable_resolution_surface.bounding_polygon = new_bounding_polygon