Quick Start Guide

This guide will help you get started with Ngawari quickly. We’ll cover the basic concepts and show you how to perform common tasks.

Basic Concepts

Ngawari provides utilities for working with VTK data objects. Three primary modules are provided:

  • ftk: Mathematical and utility functions

  • fIO: File input/output operations

  • vtkfilters: VTK filtering and processing functions

Getting Started

First, import Ngawari:

from ngawari import ftk, fIO, vtkfilters

Creating Basic Geometry

Create a sphere:

# Create a sphere at origin with radius 1.0
sphere = vtkfilters.buildSphereSource([0, 0, 0], radius=1.0)
print(f"Sphere has {sphere.GetNumberOfPoints()} points")

Create a cylinder:

# Create a cylinder
cylinder = vtkfilters.buildCylinderSource([0, 0, 0], radius=0.5, height=2.0)
print(f"Cylinder has {cylinder.GetNumberOfPoints()} points")

Working with Arrays

Get points as a NumPy array:

# Get all points from the sphere
points = vtkfilters.getPtsAsNumpy(sphere)
print(f"Points shape: {points.shape}")  # (n_points, 3)

Add a scalar array:

# Create a scalar array based on x-coordinates
x_coords = points[:, 0]
vtkfilters.setArrayFromNumpy(sphere, x_coords, "x_coordinates", SET_SCALAR=True)

Add a vector array:

# Create a vector array (example: normalized position vectors)
import numpy as np
vectors = points / np.linalg.norm(points, axis=1, keepdims=True)
vtkfilters.setArrayFromNumpy(sphere, vectors, "normals", SET_VECTOR=True)

Filtering Operations

Apply smoothing:

# Smooth the sphere
smoothed = vtkfilters.smoothTris(sphere, iterations=10)

Extract surface from volume data:

# If you have volume data, extract the surface
surface = vtkfilters.filterExtractSurface(volume_data)

Clipping and Cutting

Clip by plane:

# Clip the sphere with a plane
plane_point = [0, 0, 0]
plane_normal = [1, 0, 0]  # x-direction
clipped = vtkfilters.clipDataByPlane(sphere, plane_point, plane_normal)

Clip by sphere:

# Clip with a sphere
clip_center = [0.5, 0, 0]
clip_radius = 0.3
clipped = vtkfilters.getPolyDataClippedBySphere(sphere, clip_center, clip_radius)

File I/O

Save data to VTK format - file extension is used for format. Supported formats are:

Write

  • .vtp

  • .vts

  • .vtu

  • .stl

  • .vti

  • .mhd

  • .mha

  • .nii

Read

  • .vtp

  • .vts

  • .vtu

  • .stl

  • .vti

  • .vtk

  • .vtm

  • .nrrd

  • .mha

  • .ply

  • .nii

  • .nii.gz

  • .png

  • .jpg / .jpeg

  • .tif / .tiff

Also supports .pvd files for reading and writing - used for e.g. time series data.

# Save polydata
fIO.writeVTKFile(sphere, "sphere.vtp")

# Save image data
fIO.writeVTKFile(image_data, "image.vti")

Load data from VTK format:

# Load polydata
loaded_sphere = fIO.readVTKFile("sphere.vtp")

# Load image data
loaded_image = fIO.readVTKFile("image.vti")

Mathematical Operations

Calculate distances:

# Distance between two points
point1 = [0, 0, 0]
point2 = [1, 1, 1]
distance = ftk.distTwoPoints(point1, point2)

Vector operations:

# Normalize a vector
vector = [1, 2, 3]
normalized = ftk.normaliseArray(vector)

Complete Example

Here’s a complete example that demonstrates several features:

from ngawari import ftk, fIO, vtkfilters
import numpy as np

# Create a simple sphere
sphere = vtkfilters.buildSphereSource([0, 0, 0], radius=1.0)

# Get points as numpy array
points = vtkfilters.getPtsAsNumpy(sphere)

# Add a scalar array
vtkfilters.setArrayFromNumpy(sphere, points[:, 0], "x_coords", SET_SCALAR=True)

# Apply a filter
smoothed = vtkfilters.smoothTris(sphere, iterations=10)

# Write to file
fIO.writeVTKFile(smoothed, "smoothed_sphere.vtp")

# Build image over sphere:
image = vtkfilters.buildRawImageDataFromPolyData(smoothed, res=[0.1,0.1,0.1])

# Add a scalar array to the image
vtkfilters.setArrayFromNumpy(image, np.random.rand(image.GetNumberOfPoints()), "random_scalar", SET_SCALAR=True)

# Null scalars outside sphere
image_nulled = vtkfilters.filterNullOutsideSurface(image, smoothed)

# Write to file
fIO.writeVTKFile(image_nulled, "image_over_sphere.vti")

Next Steps

Now that you have the basics, you can explore:

For more advanced usage, check out the individual module documentation: