The slicing functions must be called in order to create data appropriate for the pl3surf (plot a 3-D surface) and pl3tree (add a plot to a tree) routines. In general, the slicing routines take a mesh specification of some sort and return a list of the form
which specifies a set of polygonal cells and how to color them.
nverts is no_cells long and the ith entry tells how many vertices the ith cell has.
xyzverts is sum (nverts) by 3 and gives the vertex coordinates of the cells in order, i. e., the first nverts [0] entries in xyzverts are the coordinates of the first polygon's vertices, the next nverts [1] entries are the coordinates of the second polygon's vertices, etc.
color, if present, is no_cells long and contains a color value for each cell in the mesh.
The function slice3mesh is designed specifically to produce an input argument for pl3surf, although if you want more than one surface in a picture, it can also be fed to pl3tree. It has several distinct calling sequences, which Python can distinguish with its type savvy.
z is a two dimensional array of function values, assumed to be on a uniform mesh nx by ny cells (assuming z is nx by ny) nx being the number of cells in the x direction, ny the number in the y direction. color, if specified, is either an nx by ny array of cell-centered values by which the surface is to be colored, or an nx + 1 by ny + 1 array of vertex-centered values, which will be averaged over each cell to give cell-centered values.
In this case, slice3mesh accepts the specification for a regular 2-D mesh: nxny is the number of cells in the x direction and the y direction; x0y0 are the initial values of x and y; and dxdy are the increments in the two directions. z is the height of a surface above the xy plane and must be dimensioned nx + 1 by ny + 1. color, if specified, is as above.
z is as above, an nx by ny array of function values on a mesh of the same dimensions. There are two choices for x and y: they can both be one-dimensional, dimensioned nx and ny respectively, in which case they represent a mesh whose edges are parallel to the axes; or else they can both be nx by ny, in which case they represent a general quadrilateral mesh.
Postponed until later in the chapter.
Slice the 3-D mesh m3 as specified by fslice, returning the list [nverts, xyzverts, color]. nverts is the number of vertices in each polygon of the slice, and xyzverts is the 3-by-sum (nverts) list of polygon vertices. If the fcolor argument is present, the values of that coloring function on the polygons are returned as the value of color. color will have the same size as nverts, i. e., the number of polygons in the slice, except that the keyword argument node, if present and nonzero, is a signal to return node-centered values rather than cell-centered values. In the latter case color will be sum (nverts) long and entries in color will be associated with the corresponding coordinates in xyzverts. nv and xyzv are not needed; None should be passed as their values (this is a leftover from an older version of the code).
fslice can be a function, a vector of 4 reals, or an integer number. If fslice is a function, it should be of the form:
or, in the case of an isosurface slice,
and should return a list of function values on the specified chunk of the mesh m3. Module slice3 offers plane and isosurface slicers (for descriptions, see page 110). If you wish to write your own slice routine, you should bear in mind that the format of chunk depends on the type of m3 mesh, so you should use only the approriate mesh functions xyz3 and getv3 which take that type of m3 and chunk as arguments. The return value of fslice should have the same dimensions as the return value of getv3; the return value of xyz3 has an additional first dimension of length 3.
If fslice is a list of 4 reals, it is taken as a slicing plane as returned by plane3.
If fslice is a single integer, the slice will be an isosurface for the fsliceth function associated with the mesh m3. In this case, the keyword value must also be present, representing the value of that function on the isosurface.
If fcolor is omitted or has value None, then slice3 returns None as the value of color.. If you want to color the polygons in a manner that depends only on their vertex coordinates (e. g., by a 3-D shading calculation), use this mode.
fcolor can be a function or a single integer. If fcolor is a function, it should be of the form:
and should return a list of function values on the specified cells of the mesh m3. If the optional argument flg1 after fcolor is not missing or None and is non-zero, then the fcolor function is called with only two arguments:
The cells argument will be the list of cell indices in m3 at which values are to be returned. l, u, fsl, fsu, and ihist are interpolation coefficients which can be used to interpolate from vertex centered values to the required cell centered values, ignoring the cells argument. See getc3 source code. The return values should always have the same size and shape as cells.
If fcolor is a single integer, then the slice will be an isosurface for the fcolorth variable associated with the mesh m3.
The functions slice2 and slice2x allow one to slice surfaces specified by slice3-type output. slice2 will return the portion on one side of the slicing plane; slice2x will return both portions.
The argument plane can be either a scalar or a plane3 (see "Creating a Plane" on page 61); nv is an array of integers, the ith entry of which gives the number of vertices of the ith polygonal cell; xyzv are the vertices of the coordinatesof the cells, with each consecutive nv [i] entries representing the vertices of the ith cell; and vals being a set of values as explained below. These arguments are the same format as returned by slice3 and slice3mesh.
If plane is a plane3, then vals (if not None) is a cell-centered set of values expressing the color of each cell, and the outputs nverts, xyzverts, and values represent the polygons and their colors (if any) describing the portion of the sliced surface that is on the positive side of the plane. That's all you get with slice2. With slice2x, you get in addition nvertb, xyzvertb, and valueb, which describe the part of the surface on the negative side of the slicing plane. Warning: one of these specifications could be None, None, None if the entire surface lies on one side of the plane.
If plane is a scalar value, then vals must be present and must be node-centered. In this case, the outputs nverts, xyzverts, and values represent the polygons and their colors (if any) describing the portion of the sliced surface where vals on the vertices are greater than or equal to the scalar value plane. (This actually allows you to form an arbitrary two-dimensional slice of a surface.) With slice2x, you get in addition nvertb, xyzvertb, and valueb, which describe the part of the surface where vals on the vertices are less than the scalar value plane.