govtk

package module
v0.0.0-...-22c5176 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 1, 2020 License: MIT Imports: 12 Imported by: 0

README

GoVTK

A Go package to write data to VTK XML files.

GoDoc Go

Note: not all feature are implemented yet. Basic VTK XML files and ParaViewData (PVD) collections are availabe.

The package supports a variety of VTK XML styles to be written, i.e. image data (.vti), rectilinear grids (.vtr), structured grids (.vts), and unstructured grids (*.vtu). Each format allows to write the XML using ascii, base64, or binary encoding. The data can be compressed using zlib by means of the Go standard library compress/zlib.

Usage

Four different formats are supported by their constructor:

  • Image() for .vti files
  • Rectilinear() for .vtr files
  • Structured() for .vts files
  • Unstructured() for .vtu files

These support three types of encoding: Ascii(), Base64(), and Raw() (binary data). The latter two result in significantly smaller files. Note, Base64() does maintain valid XML, while Raw() does not. Additionally, Base64() and Raw() encoding allow to compress the data before encoding by passing Compressed(), to further reduces file size.

Data is added by Add(). Point/Cell data can be inserted as Add(Data("fieldname", data)), which infers if the data should be place on the points or cells. Alternatively, the CellData and PointData allow to directly write data to either points or cells. Global, generic data fields can be added by FieldData.

The file is written to disk by either Save(filename string) or Write(w io.Writer). For each file type a small example is presented.

Image data
vti, err := govtk.Image(govtk.WholeExtend(0, nx, 0, ny, 0, nz))
data := make([]float64, (nx+1)*(ny+1)*(nz+1))
vti.Add(govtk.Data("fieldname", data))
vti.Save("image.vti")
Rectilinear
vtr, err := govtk.Rectilinear(govtk.WholeExtend(0, nx, 0, ny, 0, nz)) 

// store x, y, z coordinates a 1D vectors 
x := make([]float64, nx+1)
y := make([]float64, ny+1)
z := make([]float64, nz+1)

// fill x, y, z accordingly 
// ... 

// store coordinates
vtr.Add(govtk.Points(x, y, z)) 
vtr.Add(govtk.Data(...)) 
vtr.Save("rectilinear.vtr")
Structured grid
vts, err := govtk.Structured(govtk.WholeExtend(0, nx, 0, ny, 0, nz)) 

// store all x,y,z tuples for each node
xyz := make([]float64, 3*(nx+1)*(ny+1)*(nz+1))

// fill xyz with each coordinate 
// ... 

vts.Add(govtk.Points(xyz))
vts.Add(govtk.Data(...))
vts.Save("structured.vts")
Unstructured grid
vtu, err := govtk.Unstructured() 

// store all x,y,z tuples for each node 
vtu.Add(Points(...))

// provide cell connectivity, e.g. two tet elements 
conn := []int{0, 1, 2, 3, 0, 4, 5, 6}
offset := []int{0, 4, 6} // start of each element in conn 
labels := []int{20, 20} // VTK labels 

vtu.Add(govtk.Cells(conn, offset, labels))

// store data and save 
vtu.Add(govtk.Data(...))
vtk.Save("unstructured.vtu"

Paraview data file format (PVD)

The package also allows to write PVD collections. These ParaviewData files allow to store references to multiple VTK XML files, which might be located anywhere on disk. Each file can save a time step, part id, and group name as attribute. The time steps are directly available in ParaView, which is beneficial for data of transient time series.

For example to store a time series:


pvd, err := govtk.NewPVD(govtk.Directory("./mypvd")) 

// some time series 
for t := 0; t < 100; t++ {

    // generate output data 
    vti, err := govtk.Image(govtk.WholeExtend(0, nx, 0, ny, 0, nz), govkt.Raw()) 
    vti.Add(govtk.Data(...))
    
    // attach to PVD collection
    pvd.Add(vti, govtk.Time(float64(t))
}

// save PVD main file
pvd.Save(filepath.Join(pvd.Dir(), "pvd.pvd"))

Provides the following directory

myvpd/
    file_000.vti 
    file_001.vti
    ...
    file_099.vti
    pvd.pvd

Legacy format

Not yet supported

Encoding and compression settings

Basic encoding and compression is controlled by:

govtk.Ascii()     // plain ascii 
govtk.Binary()    // base64 encoding 
govtk.Raw()       // plain binary 

// compression only applies to `govtk.Binary()` and `govtk.Raw()`
govtk.Compressed()               // applies govtk.DefaultCompression
govtk.CompressedLevel(level int) // applies received compression level 

// compression levels are directly taken from `compress/zlib`
const ( 
    govtk.NoCompression      = zlib.NoCompression 
    govtk.BestSpeed          = zlib.BestSpeed
    govtk.BestCompression    = zlib.BestCompression
    govtk.DefaultCompression = zlib.DefaultCompression
    govtk.HuffmanOnly        = zlib.HuffmanOnly
)

Command-line tools

to be implemented

Installation

Install the package

go get -u -v github.com/maxvdkolk/govtk/...

References

Documentation

Index

Constants

View Source 
const (
	NoCompression      = zlib.NoCompression
	BestSpeed          = zlib.BestSpeed
	BestCompression    = zlib.BestCompression
	DefaultCompression = zlib.DefaultCompression
	HuffmanOnly        = zlib.HuffmanOnly
)

These constants are copied from the zlib package, which are in turn copied from the flat package, so that code that imports "vtu" does not also have to import "compress/zlib".

View Source 
const (
	Vertex = iota + 1
	PolyVertex
	Line
	PolyLine
	Triangle
	TriangleStrip
	Polygon
	Pixel
	Quad
	Tetra
	Voxel
	Hexahedron
	Wedge
	Pyramid
)

Linear cell types in VTK

Refer to Fig.2 https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf for the local element numbering

View Source 
const (
	QuadraticEdge = iota + 21
	QuadraticTriangle
	QuadraticQuad
	QuadraticTetra
	QuadraticHexahedron
)

Non-linear cell types in VTK

Refer to Fig.3 https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf for the local element numbering

Variables

This section is empty.

Functions

func Extent 

func Extent(x0, x1, y0, y1, z0, z1 int) func(p *partition) error

Extent sets the part of the domain given in the current partition. This should be within WholeExtent.

Types

type DSOption 

type DSOption func(d *dataSet) error

Option for the dataSet.

func Filename 

func Filename(filename string) DSOption

File sets the filename for the current header. Note: the filename is joined with the base directory of the PVD file.

func Group 

func Group(group string) DSOption

Group sets the group attribute to a header in the PVD structure.

func Part 

func Part(part int) DSOption

Part sets the part attribute to a header in the PVD structure.

func Time 

func Time(time float64) DSOption

Time sets the time step attribute to a header in the PVD structure.

func Writer 

func Writer(w io.Writer) DSOption

Writer assigns a preferred io.Writer to write this header of the PVD structure. Note: the user must ensure the file name this `io.Writer` writes to is identical to the path of `path.Join(PVD.dir, Filename)`. TODO: Filename appends to base directory of PVD, might be unclear interface.

type Grid 

type Grid struct {
	XMLName xml.Name
	Extent  bounds     `xml:"WholeExtent,attr,omitempty"`
	Origin  string     `xml:"Origin,attr,omitempty"`
	Spacing string     `xml:"Spacing,attr,omitempty"`
	Data    *dataArray `xml:"FieldData,omitempty"`
	Pieces  []partition
}

data: image or unstructured 

type Header struct {
	XMLName     xml.Name `xml:"VTKFile"`
	Type        string   `xml:"type,attr"`
	Version     float64  `xml:"version,attr"`
	ByteOrder   string   `xml:"byte_order,attr"`
	HeaderType  string   `xml:"header_type,attr,omitempty"`
	Compression string   `xml:"compressor,attr,omitempty"`
	Grid        Grid
	Appended    *darray
	// contains filtered or unexported fields
}

header of the vtu Files

func Image 

func Image(opts ...Option) (*Header, error)

Create file with image data format

func Rectilinear 

func Rectilinear(opts ...Option) (*Header, error)

Create file with rectilinear grid format

func Structured 

func Structured(opts ...Option) (*Header, error)

Create file with structured format

func Unstructured 

func Unstructured(opts ...Option) (*Header, error)

Create file with unstructured format

func (*Header) Add 

func (h *Header) Add(ops ...Option) error

Set applies a set of Options to the header

func (*Header) FileExtension 

func (h *Header) FileExtension() string

func (*Header) NewArray 

func (h *Header) NewArray() *dataArray

func (*Header) NewFieldArray 

func (h *Header) NewFieldArray() *dataArray

func (*Header) Save 

func (h *Header) Save(filename string) error

Save opens a file and writes the xml

func (*Header) Write 

func (h *Header) Write(w io.Writer) error

Encodes the xml towards a io.Writer. Writes a xml header (i.e. xml.Header constant) to the buffer first for both ascii and base64 formats. The header is omitted for formatRaw as this is actually not compliant with the xml standard.

func (*Header) WriteClose 

func (h *Header) WriteClose(w io.WriteCloser) error

Encodes the towards the WriteCloser and closes the stream after encoding.

type Option 

type Option func(h *Header) error

header options

func Appended 

func Appended() Option

func Ascii 

func Ascii() Option

func Binary 

func Binary() Option

The binary VTU format is actually base64 encoded to not break xml

func CellData 

func CellData(name string, data interface{}) Option

CellData writes the data to cell data.

func Cells 

func Cells(conn, offset, labels []int) Option

Cells sets the element connectivity of the cell in the unstructured grid. The cells are represented with three integer slices: - conn: points to coordinates (set by Points) - offsets: indicating starting point of each cell in conn - labels: element type labels for each cell (len(offsets)-1)

The user can provide a map[int]int to map the provided labels to the corresponding VTK element types. This map is set by SetLabelType().

func Compressed 

func Compressed() Option

Compressed assigns the compressor using the DefaultCompression level.

func CompressedLevel 

func CompressedLevel(level int) Option

CompressedLevel assigns the compressor using a specific compression level. Constants are provided: NoCompression, BestSpeed, BestCompression, DefaultCompression, and HuffmanOnly.

func Data 

func Data(name string, data interface{}) Option

Data adds data to the file. When len(data) matched the number of points or cells, the data is written accordingly. For ambiguous cases, the function returns an error. The PointData and CellData calls should then be considered instead.

func FieldData 

func FieldData(name string, data interface{}) Option

func Origin 

func Origin(x, y, z float64) Option

Origin sets the origin of the VTK image, rectilinear, and structured grids.

func Piece 

func Piece(opts ...func(p *partition) error) Option

func PointData 

func PointData(name string, data interface{}) Option

PointData writes the data to point data.

func Points 

func Points(xyz ...interface{}) Option

func Raw 

func Raw() Option

func SetLabelType 

func SetLabelType(labelType map[int]int) Option

SetLabelType sets the labelType map in the header. The labelType is used in unstructured grids to map the user's provided element labels towards the internal labeling.

func Spacing 

func Spacing(dx, dy, dz float64) Option

Spacing sets the spacing in x, y, z direction of the VTK image grids.

func WholeExtent 

func WholeExtent(x0, x1, y0, y1, z0, z1 int) Option

WholeExtent sets the extent of the Image, Rectilinear, or Structured grids. The extent requires a lower and upper value for each dimension, where a single dimension can be left empty, e.g. x1 - x0 == 0.

type PVD 

type PVD struct {
	XMLName xml.Name `xml:"VTKFile"`
	Type    string   `xml:"type,attr"`

	// Collection holds a data set, where each file is given by a dataSet.
	Collection []dataSet `xml:"Collection>DataSet"`
	// contains filtered or unexported fields
}

PVD represent a ParaViewData (PVD) format. The PVD file contains a single Collection, which contains multiple data sets. Each data set has a reference to a VTK file that might live anywhere on disk. Additionally, the data set allows to attach a time step, a group, and a part identifier. Providing the time steps of these files will ensure proper visualisation in ParaView of transient data sets.

func NewPVD 

func NewPVD(opts ...PVDOption) (*PVD, error)

Initialise a PVD collection with options.

func (*PVD) Add 

func (pvd *PVD) Add(h *Header, opts ...DSOption) error

Add adds a header to the PVD structure. The user can provide multiple DSOption functions to set additional details of the provided header.

func (*PVD) Dir 

func (pvd *PVD) Dir() string

Dir returns the directory of the PVD collection.

func (*PVD) Len 

func (pvd *PVD) Len() int

Len returns the number of files currently hold in the collection.

func (*PVD) Save 

func (pvd *PVD) Save(filename string) error

Save opens a file and writes the XML to file.

func (*PVD) Write 

func (pvd *PVD) Write(w io.Writer) error

Write writes the PVD as encoded XML to the provided io.Writer.

type PVDOption 

type PVDOption func(pvd *PVD) error

Options for the PVD collection.

func AbsoluteFilenames 

func AbsoluteFilenames() PVDOption

AbsoluteFilenames ensures the full pathnames are written in the PVD header.

func Directory 

func Directory(dir string) PVDOption

Directory sets the directory to store the files of the PVD collection.

func RelativeFilenames 

func RelativeFilenames() PVDOption

RelativeFilenames ensures only relative pathnames are written in PVD header.

func SetFileFormat 

func SetFileFormat(format string) PVDOption

SetFileFormat sets the formatting string for the automatic file naming. This requires a single %d for the file number and a %s for the extension.

Source Files

View all Source files

Directories

Path Synopsis
cmd
govtk

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.