0D and 1D Classes

DTPlot1D

class datatank_py.DTPlot1D.DTPlot1D(xvalues, yvalues, points_only=True)

1D Plot object.

Supported functions:

  • len()
  • for()
__init__(xvalues, yvalues, points_only=True)
Parameters:
  • xvalues – array of x values
  • yvalues – array of y values
  • points_only (boolean) – indicating whether shape information is included

The input arrays must have the same length.

If points_only is set to False, xvalues and yvalues are assumed to have the correct packed array format for a DTPlot1D, including all subpaths. Otherwise, they are assumed to define points of a single path, and the necessary subpath metadata is computed. In general, you would only pass False if reading a path from a file generated by DataTank.

In DTSource, the array has one of two formats:
  1. 2xN with a packed loop format.
  2. 4xN that saves every line segment.

In datatank_py, only the 2xN format is supported. It’s more efficient, and more compatible with DTSource manipulation.

Layout is:
DTPlot1D._xvalues = [ 0 x1 .... xN 0 x1 ... xM ...]
DTPlot1D._yvalues = [ N y1 .... yN M y1 ... yM ...]

This allows multiple loops to be saved in a single array.

DTPlot1D allows iteration over subpaths (called “loops” in DTSource), for easier manipulation and serialization of individual paths.

add_loop(xvalues, yvalues)

Add a loop (subpath) to this path.

Parameters:
  • xvalues – vector of x coordinates
  • yvalues – vector of y coordinates
number_of_loops()
Returns:number of subpaths (loops) in this path.
point_arrays()
Returns:a two-tuple with x and y vectors

Raises an exception if this path has subpaths, so iterate if you have multiple loops.

point_list()
Returns:a list of DTPoint2D objects.

Raises an exception if this path has subpaths, so iterate if you have multiple loops. Note that these loops will be single-loop paths.

>>> all_points = []
>>> for subpath in path:
...   all_points += subpath.point_list()
sparsified_path(step)
Returns:a sparsified path (copy) of the receiver.

Sparsifies by index; no smoothing or distance considerations

Sparsifies a new path by taking every N-th point, where N = step. Does not modify the original path object. If a closed path was passed in, the returned path is also closed. Raises an exception if sparsifying any subpath would result in fewer than 2 points.

DTMask

class datatank_py.DTMask.DTMask(mask_values)

Mask object corresponding to DataTank’s DTMask.

This is typically used to mask out a portion of a mesh or structured grid. Note that not all mesh types support a mask in DataTank.

The internal storage for this object mimics that used in DTSource’s C++ DTMask. It’s very compact, but can be confusing to work with. If you’re doing manual hit-testing, it’s easiest to just use datatank_py.DTMask.DTMask.mask_array() to get an array matching the logical shape of your masked object.

__init__(mask_values)

Create a new mask.

mask_values
array of ones and zeroes, covering the full extent of the array to be masked.
dt_type = ('Mask', 'DTMask')

Type strings allowed by DataTank

classmethod from_data_file(datafile, name)

Instantiates a datatank_py.DTMask.DTMask from a datatank_py.DTDataFile.DTDataFile, using the given variable name

m()

first logical dimension

mask_array()

Returns a full uint8 mask array in the original mask shape

n()

second logical dimension

o()

third logical dimension

DTDictionary

class datatank_py.DTDictionary.DTDictionary

Dictionary object.

DataTank dictionaries can only contain scalars, strings, arrays of numbers, or other dictionaries as values. Keys are always strings. Other than that, usual Python dictionary semantics apply for access and iteration.

Supported functions:

  • len()
  • for()
  • in()
#!/usr/bin/env python
# -*- coding: utf-8 -*-

from datatank_py.DTDataFile import DTDataFile
from datatank_py.DTDictionary import DTDictionary

if __name__ == '__main__':

    dt_dict = DTDictionary()

    dt_dict["Test_scalar_float"] = 2.573
    dt_dict["Test_scalar_int"] = 5
    dt_dict["Test_string"] = "This is only a test"
    dt_dict["Test_array"] = (1.1, 2, 5, 7.5, 11.978)

    with DTDataFile("/tmp/dict_test.dtbin", truncate=True) as dtf:
        dtf["dictionary test"] = dt_dict

    # read the dictionary back from the file
    with DTDataFile("/tmp/dict_test.dtbin") as dtf:
        dt_dict = DTDictionary.from_data_file(dtf, "dictionary test")

        # iterate and print each key/value pair
        for k in dt_dict:
            print "%s = %s" % (k, dt_dict[k])

        # normal dictionary print
        print dt_dict

2D Classes

DTMesh2D

class datatank_py.DTMesh2D.DTMesh2D(values, grid=None, mask=None)

2D Mesh object.

This class corresponds to DataTank’s DTMesh2D object. Note that a 2D Mesh object is always single or double precision floating point, so integer values will be converted.

__init__(values, grid=None, mask=None)
Parameters:
  • values – 2D array of values
  • grid – (xmin, ymin, dx, dy) or None for unit grid
  • mask – a datatank_py.DTMask.DTMask instance
dt_type = ('2D Mesh', 'Mesh2D')

Type strings allowed by DataTank

grid()
Returns:tuple with (xmin, ymin, dx, dy)
mask()
Returns:a datatank_py.DTMask.DTMask instance or None
values()
Returns:numpy array of floating-point values at each grid node

DTPoint2D

class datatank_py.DTPoint2D.DTPoint2D(x, y)

2D Point object.

This could really be a two-tuple, but we need to be able to serialize it properly to a datafile.

__init__(x, y)
Parameters:
  • x – x coordinate
  • y – y coordinate
dt_type = ('2D Point',)

Type strings allowed by DataTank

x = None
Member x:x coordinate
y = None
Member y:y coordinate

DTPointCollection2D

class datatank_py.DTPointCollection2D.DTPointCollection2D(xvalues, yvalues)

2D Point collection object.

Supported functions:

  • len()
  • for()
  • indexed access, e.g., foo[2] to get the second point
__init__(xvalues, yvalues)
Parameters:
  • xvalues – array of x values
  • yvalues – array of y values

Pass empty arrays to get an empty collection that can be added to with add_point().

add_point(point)

Add a point to the collection

Parameters:point – a datatank_py.DTPoint2D.DTPoint2D instance
bounding_box()
Returns:tuple with (xmin, xmax, ymin, ymax)
dt_type = ('2D Point Collection',)

Type strings allowed by DataTank

DTPointValue2D

class datatank_py.DTPointValue2D.DTPointValue2D(x, y, value)

2D Point Value object.

__init__(x, y, value)
Parameters:
  • x – x coordinate
  • y – y coordinate
  • value – scalar value at this point
dt_type = ('2D Point Value',)

Type strings allowed by DataTank

value = None
Member value:scalar value at this point
x = None
Member x:x coordinate
y = None
Member y:y coordinate

DTPointValueCollection2D

class datatank_py.DTPointValueCollection2D.DTPointValueCollection2D(points, values)

2D Point Value collection object.

Supported functions:

  • len()
  • for()
  • indexed access, e.g., foo[2] to get the second point
__init__(points, values)
Parameters:

Point collection and values may be empty (length zero), but not None.

add_point_value(point, value)
Parameters:
bounding_box()
Returns:result of datatank_py.DTPointCollection2D.DTPointCollection2D.bounding_box()
dt_type = ('2D Point Value Collection',)

Type strings allowed by DataTank

points()
Returns:a datatank_py.DTPointCollection2D.DTPointCollection2D instance
values()
Returns:vector of scalar values

DTStructuredGrid2D

class datatank_py.DTStructuredGrid2D.DTStructuredGrid2D(x, y, mask=None)

2D structured grid object.

This class corresponds to DataTank’s DTStructuredGrid2D.

__init__(x, y, mask=None)
Parameters:
  • x – vector or 2D array of x values
  • y – vector or 2D array of y values
  • mask – optional datatank_py.DTMask.DTMask object

Note: if a full 2D array is passed, it must be ordered as (y, x) for compatibility with DataTank. When using vectors, this is handled automatically.

bounding_box()
Returns:a datatank_py.DTRegion2D.DTRegion2D instance
dt_type = ('2D Structured Grid',)

Type strings allowed by DataTank

full_x()
Returns:a 2D array of all x-values
full_y()
Returns:a 2D array of all y-values
mask()
Returns:a datatank_py.DTMask.DTMask instance or None
shape()
Returns:the logical grid size (y, x), even if stored as vectors.

DTStructuredMesh2D

class datatank_py.DTStructuredMesh2D.DTStructuredMesh2D(values, grid=None)

2D structured mesh object.

This class corresponds to DataTank’s DTStructuredMesh2D.

__init__(values, grid=None)
Parameters:
  • values – 2D array of values
  • grid – DTStructuredGrid2D object (defaults to unit grid) or the name of a previously saved grid

Note that the values array must be ordered as (y, x) for compatibility with the grid and DataTank.

dt_type = ('2D Structured Mesh',)

Type strings allowed by DataTank

grid()
Returns:a datatank_py.DTStructuredGrid2D.DTStructuredGrid2D instance
values()
Returns:a 2D numpy array of values at each grid node
write_with_shared_grid(datafile, name, grid_name, time, time_index)

Allows saving a single grid and sharing it amongst different time values of a variable.

Parameters:
  • datafile – a datatank_py.DTDataFile.DTDataFile open for writing
  • name – the mesh variable’s name
  • grid_name – the grid name to be shared (will not be visible in DataTank)
  • time – the time value for this step (DataTank’s t variable)
  • time_index – the corresponding integer index of this time step

This is an advanced technique, but it can give a significant space savings in a data file. It’s not widely implemented, since it’s not clear yet if this is the best API.

DTStructuredVectorField2D

class datatank_py.DTStructuredVectorField2D.DTStructuredVectorField2D(u, v, grid=None)

2D vector field on a structured grid.

__init__(u, v, grid=None)
Parameters:

Note that the u, v arrays must be arranged as (y, x) for compatibility with the grid and DataTank.

dt_type = ('2D Structured Vector Field',)

Type strings allowed by DataTank

grid()
Returns:a datatank_py.DTStructuredGrid2D.DTStructuredGrid2D instance
u()
Returns:u component of vector field (2D array)
v()
Returns:v component of vector field (2D array)

DTTriangularGrid2D

class datatank_py.DTTriangularGrid2D.DTTriangularGrid2D(connections, points)

2D triangular grid object. This is a collection of points interconnected to form triangles. DataTank does not support a mask for this type of grid, but it’s very useful for creating 3D surfaces and certain computations.

__init__(connections, points)
Parameters:
  • connections – 2D array of connections [ m x 3 ]
  • points – 2D array of points [ m x 2 ]

Each x,y node is connected to three other nodes, as seen in this contrived example:

Point Index Point X Point Y Connection 1 Connection 2 Connection 3
0 1.0 1.0 0 1 112
1 2.0 1.0 112 1 114
2 3.0 3.0 113 1 114
… … … … … …
m 99.0 99.0 m-1 m-20 m-57

The values in the connections array refer to point indices, and allow reconstruction of the unstructured triangular network.

Note that DataTank expects zero-based connection indices.

bounding_box()
Returns:a datatank_py.DTRegion2D.DTRegion2D instance
dt_type = ('2D Triangular Grid',)

Type strings allowed by DataTank

number_of_points()
Returns:the number of points in the grid

DTTriangularMesh2D

class datatank_py.DTTriangularMesh2D.DTTriangularMesh2D(grid, values)

2D triangular mesh object.

__init__(grid, values)
Parameters:
bounding_box()
Returns:a datatank_py.DTRegion2D.DTRegion2D instance
dt_type = ('2D Triangular Mesh',)

Type strings allowed by DataTank

grid()
Returns:a datatank_py.DTTriangularGrid2D.DTTriangularGrid2D instance
write_with_shared_grid(datafile, name, grid_name, time, time_index)

Allows saving a single grid and sharing it amongst different time values of a variable.

Parameters:
  • datafile – a datatank_py.DTDataFile.DTDataFile open for writing
  • name – the mesh variable’s name
  • grid_name – the grid name to be shared (will not be visible in DataTank)
  • time – the time value for this step (DataTank’s t variable)
  • time_index – the corresponding integer index of this time step

This is an advanced technique, but it can give a significant space savings in a data file. It’s not widely implemented, since it’s not clear yet if this is the best API, but the following example shows how it’s used:

#!/usr/bin/env python

import numpy as np

from datatank_py.DTDataFile import DTDataFile
from datatank_py.DTTriangularGrid2D import DTTriangularGrid2D
from datatank_py.DTTriangularMesh2D import DTTriangularMesh2D

# files that exist in the current directory
grid_filename = "grid.txt"

# this is a time-varying list of depths at each node
depth_filename = "depths.txt"

# function that returns a DTTriangularGrid2D
grid = parse_grid_from_path(grid_filename)

# this can be any string; the user won't see it
shared_grid_name = grid_filename

with DTDataFile("Output.dtbin", truncate=True) as dtf:
    
    # a bunch of this is related to parsing the textfile                
    with open(depth_filename, "rU") as asciivalues:
        
        # here we have some state variables, but the time ones are relevant
        passed_header = False
        accumulated_values = []
        
        # this is a time extracted from the file (a floating point value)
        timeval = None
        
        # this is the zero-based index of the timeval
        time_index = 0
        
        # this is the initial value of the timeval variable
        base_timeval = None
        
        for lineidx, line in enumerate(asciivalues):
            
            line = line.strip()
            if line.startswith("TS"):
                
                # If we've already seen a timeval, a "TS" marker means that we're starting 
                # another block of depth values so we're going to save the previous 
                # timestep to disk.
                if timeval is not None:
                    assert passed_header is True
                    
                    # save the t0 if we haven't already done so
                    if base_timeval is None:
                        base_timeval = timeval
                        
                    # create a DTTriangularMesh2D as usual, with grid and values
                    # note that a 32-bit float will save significant space over
                    # a double, if you can live with the reduced precision.
                    mesh = DTTriangularMesh2D(grid, np.array(accumulated_values, dtype=np.float32))
                    
                    # This is the floating point time value that will be used for
                    # DataTank's time slider. Here I'm using hours.
                    dttime_hours = (timeval - base_timeval) / 3600.
                    
                    # Now, save it off. The variable in the file will be visible as "Depth",
                    # and write_with_shared_grid() will take care of saving the grid for the
                    # first time and then saving the name on subsequent time steps.
                    #
                    # The dttime_hours variable is our slider time, and time_index is passed
                    # so that write_with_shared_grid() can create the correct variable name,
                    # i.e., "Depth_0, Depth_1, Depth_2, … Depth_N" for successive time steps.
                    #
                    mesh.write_with_shared_grid(dtf, "Depth", shared_grid_name, dttime_hours, time_index)
                    
                    #
                    # This code shows what write_with_shared_grid() is really doing in our specific
                    # example:
                    #
                    # dtf.write(mesh, "Depth_%d" % (time_index), time=(timeval - base_timeval))
                    # dtf.write_anonymous(shared_grid_name, "Depth_%d" % (time_index))
                    # dtf.write_anonymous(np.array(accumulated_values).astype(np.float32), "Depth_%d_V" % (time_index))
                    # dtf.write_anonymous(np.array((timeval - base_timeval,)), "Depth_%d_time" % (time_index))
                    
                    time_index += 1
                
                # update our state variables and continue parsing the file    
                ts, zero, time_str = line.split()
                timeval = float(time_str)
                
                # this will be the start of a new vector of depth values
                accumulated_values = []
                passed_header = True
        
            elif passed_header and not line.startswith("ENDDS"):
                # here we're just saving off an individual depth value for a node
                accumulated_values.append(float(line))    
            else:
                print "Ignored: %s" % (line)

DTTriangularVectorField2D

class datatank_py.DTTriangularVectorField2D.DTTriangularVectorField2D(grid, u, v)

2D triangular vector field object.

__init__(grid, u, v)
Parameters:
bounding_box()
Returns:a datatank_py.DTRegion2D.DTRegion2D instance
dt_type = ('2D Triangular Vector Field',)

Type strings allowed by DataTank

grid()
Returns:a datatank_py.DTTriangularGrid2D.DTTriangularGrid2D instance
write_with_shared_grid(datafile, name, grid_name, time, time_index)

Allows saving a single grid and sharing it amongst different time values of a variable.

Parameters:
  • datafile – a datatank_py.DTDataFile.DTDataFile open for writing
  • name – the vector field variable’s name
  • grid_name – the grid name to be shared (will not be visible in DataTank)
  • time – the time value for this step (DataTank’s t variable)
  • time_index – the corresponding integer index of this time step

This is an advanced technique, but it can give a significant space savings in a data file. It’s not widely implemented, since it’s not clear yet if this is the best API.

For an example, see datatank_py.DTTriangularMesh2D.DTTriangularMesh2D.write_with_shared_grid()

DTPath2D

class datatank_py.DTPath2D.DTPath2D(xvalues, yvalues, points_only=True)

2D Path object.

Supported functions:

  • len()
  • for()
__init__(xvalues, yvalues, points_only=True)
Parameters:
  • xvalues – array of x values
  • yvalues – array of y values
  • points_only (boolean) – indicating whether shape information is included

The input arrays must have the same length.

If points_only is set to False, xvalues and yvalues are assumed to have the correct packed array format for a DTPath2D, including all subpaths. Otherwise, they are assumed to define points of a single path, and the necessary subpath metadata is computed. In general, you would only pass False if reading a path from a file generated by DataTank.

In DTSource, the array has one of two formats:
  1. 2xN with a packed loop format.
  2. 4xN that saves every line segment.

In datatank_py, only the 2xN format is supported. It’s more efficient, and more compatible with DTSource manipulation.

Layout is:
DTPath2D._xvalues = [ 0 x1 .... xN 0 x1 ... xM ...]
DTPath2D._yvalues = [ N y1 .... yN M y1 ... yM ...]

This allows multiple loops to be saved in a single array.

DTPath2D allows iteration over subpaths (called “loops” in DTSource), for easier manipulation and serialization of individual paths.

add_loop(xvalues, yvalues)

Add a loop (subpath) to this path.

Parameters:
  • xvalues – vector of x coordinates
  • yvalues – vector of y coordinates
bounding_box()
Returns:a 4-tuple (xmin, xmax, ymin, ymax)
number_of_loops()
Returns:number of subpaths (loops) in this path.
point_list()
Returns:a list of DTPoint2D objects.

Raises an exception if this path has subpaths, so iterate if you have multiple loops. Note that these loops will be single-loop paths.

>>> all_points = []
>>> for subpath in path:
...   all_points += subpath.point_list()
sparsified_path(step)
Returns:a sparsified path (copy) of the receiver.

Sparsifies by index; no smoothing or distance considerations

Sparsifies a new path by taking every N-th point, where N = step. Does not modify the original path object. If a closed path was passed in, the returned path is also closed. Raises an exception if sparsifying any subpath would result in fewer than 2 points.

DTPathValues2D

class datatank_py.DTPathValues2D.DTPathValues2D(path, values)

2D Path Values object. This is a 2D path, with a scalar value defined at each point.

Supported functions:

  • len()
  • for()
__init__(path, values)
Parameters:

The inputs must have the same length. Values will be packed to match the internal format of DTPath2D.

path()
Returns:the underlying path (which may have subpaths)
values()
Returns:vector of values at each point in the path

DTRegion2D

class datatank_py.DTRegion2D.DTRegion2D(xmin=0, xmax=0, ymin=0, ymax=0)

2D region object.

This is a rectangle, commonly used for cropping regions and bounding boxes of objects. It’s mainly provided for compatibility with reading and writing other objects.

__init__(xmin=0, xmax=0, ymin=0, ymax=0)
Parameters:
  • xmin – left side x
  • xmax – right side x
  • ymin – bottom y
  • ymax – top y

Arguments are converted to double precision.

dt_type = ('2D Region', 'Region2D')

Type strings supported by DataTank

DTVector2D

class datatank_py.DTVector2D.DTVector2D(x, y, u, v)

2D Vector object.

__init__(x, y, u, v)
Parameters:
  • x – x location
  • y – y location
  • u – x magnitude
  • v – y magnitude
dt_type = ('2D Vector',)

Type strings allowed by DataTank

3D Classes

DTRegion3D

class datatank_py.DTRegion3D.DTRegion3D(xmin=0, xmax=0, ymin=0, ymax=0, zmin=0, zmax=0)

3D region object.

This is a rectangular box, commonly used for cropping regions and bounding boxes of objects. It’s mainly provided for compatibility with reading and writing other objects.

dt_type = ('3D Region', 'Region3D')

Type strings supported by DataTank

DTStructuredGrid3D

class datatank_py.DTStructuredGrid3D.DTStructuredGrid3D(x, y, z, mask=None)

3D structured grid object.

This class corresponds to DataTank’s DTStructuredGrid3D.

__init__(x, y, z, mask=None)
Parameters:
  • x – vector or 3D array of x values
  • y – vector or 3D array of y values
  • z – vector or 3D array of z values
  • mask – optional datatank_py.DTMask.DTMask object

Note: if a full 3D array is passed, it must be ordered as (z, y, x) for compatibility with DataTank. When using vectors, this is handled automatically.

bounding_box()
Returns:a datatank_py.DTRegion3D.DTRegion3D instance
dt_type = ('3D Structured Grid',)

Type strings allowed by DataTank

full_x()
Returns:a 3D array of all x-values
full_y()
Returns:a 3D array of all x-values
full_z()
Returns:a 3D array of all x-values
shape()
Returns:the logical grid size (z, y, x), even if stored as vectors.
slice_xy(zero_based_slice_index)

Slice the grid based on index in the Z dimension.

Parameters:zero_based_slice_index – slice index, which is zero-based (unlike DataTank, which is 1-based)
Returns:a datatank_py.DTStructuredGrid2D.DTStructuredGrid2D instance
slice_xz(zero_based_slice_index)

Slice the grid based on index in the X dimension.

Parameters:zero_based_slice_index – slice index, which is zero-based (unlike DataTank, which is 1-based)
Returns:a datatank_py.DTStructuredGrid2D.DTStructuredGrid2D instance
slice_yz(zero_based_slice_index)

Slice the grid based on index in the Y dimension.

Parameters:zero_based_slice_index – slice index, which is zero-based (unlike DataTank, which is 1-based)
Returns:a datatank_py.DTStructuredGrid2D.DTStructuredGrid2D instance

DTStructuredMesh3D

class datatank_py.DTStructuredMesh3D.DTStructuredMesh3D(values, grid=None)

3D structured mesh object.

This class corresponds to DataTank’s DTStructuredMesh3D.

dt_type = ('3D Structured Mesh',)

Type strings allowed by DataTank

grid()
Returns:datatank_py.DTStructuredGrid3D.DTStructuredGrid3D instance
slice_xy(zero_based_slice_index)

Slice the grid based on index in the Z dimension.

Parameters:zero_based_slice_index – slice index, which is zero-based (unlike DataTank, which is 1-based)
Returns:a datatank_py.DTStructuredMesh2D.DTStructuredMesh2D instance
slice_xz(zero_based_slice_index)

Slice the mesh based on index in the X dimension.

Parameters:zero_based_slice_index – slice index, which is zero-based (unlike DataTank, which is 1-based)
Returns:a datatank_py.DTStructuredMesh2D.DTStructuredMesh2D instance
slice_yz(zero_based_slice_index)

Slice the mesh based on index in the Y dimension.

Parameters:zero_based_slice_index – slice index, which is zero-based (unlike DataTank, which is 1-based)
Returns:a datatank_py.DTStructuredMesh2D.DTStructuredMesh2D instance

DTStructuredVectorField3D

class datatank_py.DTStructuredVectorField3D.DTStructuredVectorField3D(u, v, w, grid=None)

3D vector field on a structured grid.

__init__(u, v, w, grid=None)
Parameters:

Note that the u, v, w arrays must be arranged as (z, y, x) for compatibility with the grid and DataTank.

grid()
Returns:a datatank_py.DTStructuredGrid3D.DTStructuredGrid3D instance
u()
Returns:u component of vector field (3D array)
v()
Returns:v component of vector field (3D array)
w()
Returns:w component of vector field (3D array)