StructuredGrid tutorials and add blank points/cells

[banesullivan]

We need to create a tutorial for structured grids that walks users through how to create many different types/configurations of structured grids.

The main point of confusion I see is with what the dimensions mean - most users expect this to be the number of points in each axial direction, and this will work for most users. However, the dimensions really only care about the structure of the points array and are indifferent about how many nodes are in each axial direction. I think one of the best examples to demo this point is a very curved structured grid-like (we should make a simpler example though - too much code in this):

Maybe check out this example for something better

import numpy as np
import pyvista as pv

# Adapted from https://stackoverflow.com/questions/11331854/how-can-i-generate-an-arc-in-numpy

N = 30

def parametric_circle(t, xc, yc, R):
    x = xc + R*np.cos(t)
    y = yc + R*np.sin(t)
    return x, y

def inv_parametric_circle(x, xc, R):
    t = np.arccos((x-xc)/R)
    return t

def make_arch(R):
    xc = 1.0
    yc = 3.0
    
    start_point = (xc + R*np.cos(.3), yc + R*np.sin(.3))
    end_point   = (xc + R*np.cos(2.2), yc + R*np.sin(2.2))

    start_t = inv_parametric_circle(start_point[0], xc, R)
    end_t   = inv_parametric_circle(end_point[0], xc, R)

    arc_T = np.linspace(start_t, end_t, N)
    x, y = parametric_circle(arc_T, xc, yc, R)
    return np.c_[x, y, np.zeros_like(x)]


points = np.empty((0, 3))
radii = [3.5, 3.0, 2.75, 2.5, 1.75,]
for radius in radii:
    points = np.append(points, make_arch(radius), axis=0)


mesh = pv.StructuredGrid()
mesh.points = points
mesh.dimensions = (1, N, len(radii))
mesh.plot(show_edges=True, cpos='xy')

[banesullivan]

Also, blank points are an interesting concept we might want to mention in this tutorial. We may need to add a wrapper to handle bank points more intuitively so that a user could pass an array of indices and have the render window automatically hide those points much like this VTK example.

Perhaps we should mark any points with a NaN value as blank in StructuredGrids?

And here's a snippet with PyVista:

import numpy as np
import pyvista as pv

mesh = pv.StructuredGrid(*np.meshgrid(np.arange(8), np.arange(8), [1,]))
mesh.BlankPoint(27)
mesh.Modified()
mesh.plot(show_edges=True, cpos='xy', color='white', background='green')

mesh.plot(show_edges=True, cpos='xy', scalars=np.arange(mesh.n_points), 
          background='green', cmap='Reds')

And a 3D example:

mesh = pv.StructuredGrid(*np.meshgrid(np.arange(8), np.arange(8), np.arange(8)))
mesh.BlankPoint(mesh.n_points-1)
mesh.BlankPoint(mesh.n_points-6)
mesh.Modified()
mesh.plot(show_edges=True, color='white', background='green')

[banesullivan]

Perhaps we should mark any points with a NaN value as blank in StructuredGrids?

The issue with doing this for point arrays is that some arrays might have a NaN value where another array has a value.

Goal

It may be simplest and most versatile if we simply add a property (setter/getter) for marking blank points on StructuredGrids:

...
>>> mesh.blank_points = [0, 3, 4, 27, 28]
>>> mesh.blank_points
[0, 3, 4, 27, 28]

and same for bank cells:

...
>>> mesh.blank_cells = [1, 5, 18]
>>> mesh.blank_cells
[1, 5, 18]

Implementation

To implement this, we'd have to keep an internal reference array bound to the mesh sinceany user changes to the'vtkGhostType' array (this array is added to the mesh when calling BlankPoint or BlankCell) will not change the marked blank points/cells - there's UpdatePointGhostArrayCache() and UpdateCellGhostArrayCache() methods that don't seem to help. For example:

...
>>> mesh.BlankPoint(27) # this adds a new `'vtkGhostType'` array
>>> np.argwhere(mesh['vtkGhostType'])
array([[27]])
>>> mesh['vtkGhostType'][3] = 1
>>> np.argwhere(mesh['vtkGhostType'])
array([[ 3],
       [27]])
>>> mesh.UnBlankPoint(27)
>>> mesh.UpdatePointGhostArrayCache()
>>> np.argwhere(mesh['vtkGhostType'])
array([[3]])
>>> mesh.HasAnyBlankPoints()
False

the last result is False when we'd expect True - thus manually changing the 'vtkGhostType' array does not affect the blank points/cells.

[banesullivan]

FYI, I very recently added a wonderful helper method for creating cylinder StructuredGrids:

import pyvista as pv

# Surface of cylinder
pv.CylinderStructured(radius=2).plot(show_edges=True)

# Full 3D cylinder with 2 radial cells
pv.CylinderStructured(radius=[2, 2.5, 3]).plot(show_edges=True)