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