ViSUSpy

ViSUSpy is a library that allows the user to use the ViSUS framework from python.

In the following sections we provide some examples on how to use it.

Library imports

To import and use the library in your python application you need to use the following imports:

from visuspy import *
from VisusKernelPy import *
from VisusIdxPy    import *
from VisusDbPy     import *

These modules allow the basic interactions with IDX datasets, which can be either local or remote (served by a ViSUS Server).

Important: your code that interacts with IDX datasets has always to attach the IdxModule first, as following:

IdxModule.attach()
# your program code
IdxModule.detach()

NumPy utils

In order to facilitate interoperation with existing python scientific libraries as NumPy we provide two function to convert data arrays from/to ViSUS Array an NumPy array.

import numpy

# convert our buffer to a numpy array.
# This is useful when we want to read data from 
# and IDX dataset and use this array with other libraries
numpy_array=convertToNumPyArray(in_visus_array)

# convert a numpy array to a ViSUS array
visus_array = convertToVisusArray(numpy_array)

Write data in IDX format

IdxModule.attach()

# define a box which defines the bounding box
# of the grid where our data will be stored
# a box is defined by two points (p1 and p2)
# which define the two opposite corners of the box
# in this case the box has size 16x16x16
dataset_box=NdBox(NdPoint(0,0,0),NdPoint.one(16,16,16))
    
# create and IDX file where to to store the data
idxfile=IdxFile();

# set dataset box
idxfile.box=NdBox(dataset_box)

# add integer field to the dataset
idxfile.fields.push_back(Field("myfield",DType.fromString("uint32")))

# save the metadata on disk (no data are saved yet)
bSaved=idxfile.save(self.filename)
self.assertTrue(bSaved)

# load the dataset we just created    
dataset=Dataset.loadDataset(self.filename)
self.assertIsNotNone(dataset)

# create access to write the data
access=dataset.createAccess()

# write data slice by slice    
sampleid=0    
for Z in range(0,16):
  # create box to hold the Z slice of the data
  slice_box=dataset.getBox().getZSlab(Z,Z+1)
  
  # create write query 
  query=Query(dataset,ord('w'))
  # set query box
  query.position=Position(slice_box)
      
  # initialize query
  self.assertTrue(dataset.beginQuery(query))
  # check if size of the query is equal to the dimension of our dataset
  self.assertEqual(query.nsamples.innerProduct(),16*16)
  
  # create a Visus Array to store the data
  buffer=Array(query.nsamples,query.field.dtype)
  # set the output buffer of the query to the array we just created
  query.buffer=buffer
      
  # convert our buffer to a numpy array 
  fill=toNumPy(buffer)

  # fill up the array with some values
  for Y in range(16):
    for X in range(16):
      fill[Y,X]=sampleid
      sampleid+=1

# execute query
success = dataset.executeQuery(access,query)

IdxModule.detach()

Read from IDX file

IdxModule.attach()

# open an IDX dataset
dataset=Dataset_loadDataset(self.filename)
# check it is valid
self.assertIsNotNone(dataset)

# get the bounding box of the dataset 
# the box is defined by a set of 2 points (p1 and p2)
# which define the two corners of a bounding box
box=dataset.getBox()

# get the default field of a dataset
field=dataset.getDefaultField()

#create access
access=dataset.createAccess()

# here we read the datasets slice by slice
# making box queries 
sampleid=0
for Z in range(0,16):
  slice_box=box.getZSlab(Z,Z+1)
      
  # define a read query
  query=Query(dataset,ord('r'))
  # set the box for the query
  query.position=Position(slice_box)
      
  self.assertTrue(dataset.beginQuery(query))
  # check the size of the output of the query 
  print("query size", query.nsamples.innerProduct())
  # execute query
  self.assertTrue(dataset.executeQuery(access,query))
  
  # convert output buffer to a numpy array
  my_numpy_array=toNumPy(query.buffer)

IdxModule.detach()