4. geometry_extractor

Extract geoemtric features – surfaces and lines – from periodic volumetric data.

Note: This module uses pyopencl (via simple_cl) for computations.

4.1. Example Usage

#First generate a periodic volume -- in this case a unit cell of a gyroid.

NP = 128
x = np.arange(NP) * 2*np.pi / NP - np.pi
x = x.reshape(1, 1, NP)
y = x.reshape(1, NP, 1)
z = x.reshape(NP, 1, 1)

gyroid = np.sin(x) * np.cos(y) + np.sin(y) * np.cos(z) + np.sin(z) * np.cos(x)

#Generate a mesh as a gyroid isosurface
m = periodic_isosurface(gyroid, level=0)

#Save the mesh as a PLY file
m.save('gyroid.ply') #Use the mesh.save

geometry_extractor can also be used in conjunction with an external CLSession by specifying the clsession parameter in the relevant function calls. This may dramatically speed up certain operations by preventing data copying. Note that any function calls to with a specified clsession will automatically compile the geometry extractor kernels for that OpenCL context.

4.2. Overview

periodic_isosurface(arr[, level, clsession])	Generate an isosurface for periodic volumetric data.
periodic_complex_trace(arr[, min_dist, …])	Trace the zero lines in a complex periodic array
periodic_interpolate(arr, points[, clsession])	Get the interpolated value of periodic volumetric data.
periodic_label(mask[, structure])	Label non-zero features in a periodic array.
periodic_path_unwrap(X, period)	Make a path generated from a periodic volume smooth by moving sections across period boundaries.
set_opencl_params([use_doubles, device, context])	Set the parameters of the OpenCL Session used for computations.
compile_code_in_external_session(cl)	Compile the geometry extractor kernel in an external CLSession.

4.3. Classes and Functions

ilpm.geometry_extractor.compile_code_in_external_session(cl)

Compile the geometry extractor kernel in an external CLSession.

Allows this session to be used with geometry extractor calls. Usually this function does not need to be called explicitly, but will be handled automatically when a function which requires it is called.

Parameters

clilpm.simple_cl.CLSession

ilpm.geometry_extractor.set_opencl_params(use_doubles=None, device=None, context=None)

Set the parameters of the OpenCL Session used for computations.

See simple_cl documentation for details.

Note: this function must be called before any functions that use it, or an error will be raised.

Parameters

use_doublesbool, optional (default: False)

devicestring or list, optional (default: ‘cpu’)

contextpyopencl Context or CLSession object, optional

If specified, causes CLSession to share a context.

ilpm.geometry_extractor.periodic_isosurface(arr, level=0, clsession=None)

Generate an isosurface for periodic volumetric data.

Parameters

arrnumpy or pyopencl array

Array should be real or complex type of the CL session (default: float32 or complex64). If array is complex type, the isosurface is taken as the absolute value of the array. (This is useful because it doesn’t make a copy of the array, so it doesn’t use any extra memory.)

levelfloat

The value at which to take the isosurface.

clsessionilpm.simple_cl.CLSession, optional

If specified, kernel will be run using specified CL session, otherwise a default one is automatically generated. If the required kernels are not found in the clsession, they will be automatically compiled.

Returns

meshilpm.mesh.Mesh

A mesh corresponding to the volume. The coordinates correspond to the indices of the input array, and the normals are automatically generated from the volumetric data.

ilpm.geometry_extractor.periodic_complex_trace(arr, min_dist=0.25, ignore_length=3, link_angle=1.0471975511965976, clsession=None)

Trace the zero lines in a complex periodic array

Parameters

arrnumpy or pyopencl array

min_distfloat, optional (default: 0.25)

The minimum distance between points in the returned Tangle. Used as an input to ilpm.path.Tangle.eliminate_close_points().

ignore_lengthint, optional (default: 3)

Paths with a length less than or equal to this number of points are silently ignored.

link_anglefloat, optional (default: pi/3 ~ 60 deg)

The maximum angle between a tangent vector and the radius vector between two points for a valid link. Larger values accomidate more sharply curved paths, but have a higher probability of forming false connections which will result in a failed trace.

clsessionilpm.simple_cl.CLSession, optional

If specified, kernel will be run using specified CL session, otherwise a default one is automatically generated. If the required kernels are not found in the clsession, they will be automatically compiled.

Returns

tangleilpm.path.Tangle

A tangle of the traced paths. If there are errors in the trace, this will be indicated in the tangle.info['trace_error'] field. In addition to the traced paths, the zero-phase direction will be included in the tangle as the normal vector for each path.

bad_tracesint

The number of non-closed paths. Should be 0 for a sucessful trace.

ilpm.geometry_extractor.periodic_path_unwrap(X, period)

Make a path generated from a periodic volume smooth by moving sections across period boundaries.

Does not take :class:ilpm.path.Path’s as input; this function should be called before turning the vector array into a path.

After completing the unwrapping, ensures that all points lie on the positive side of the periodic boundary, i.e. if any coordinate is negative in the path it pushes it up one period.

Parameters

Xvector (N, 3) array

period(3) array

Returns

Xpvector (N, 3) array

A reconnected version of X. Some points may lie outside the original period, as required for reconnecting the sections.

ilpm.geometry_extractor.periodic_label(mask, structure=None)

Label non-zero features in a periodic array.

This function is an extension to scipy.ndimage.measurements.label, which connects regions across periodic boundaries.

Parameters

mask: array_like

An array to be labeled. All non-zero regions considered features.

Returns

labelnumpy array

An integer array where each value represents the (arbitrary) feature number

num_featuresint

The number of features.

ilpm.geometry_extractor.periodic_interpolate(arr, points, clsession=None)

Get the interpolated value of periodic volumetric data.

Parameters

arrvolumetric array

Should be real of complex type.

pointsvector array [shape: (…, 3)]

Coordinates of points to map. (Note: “C” indexing assumed, thus point (1, 2, 3) maps to arr[3, 2, 1].)

clsessionilpm.simple_cl.CLSession, optional

If specified, kernel will be run using specified CL session, otherwise a default one is automatically generated. If the required kernels are not found in the clsession, they will be automatically compiled.

Returns

valuearray [shape: (…)]