cigvis.vispyplot module#

Functions for drawing 3D seismic figure using vispy#

Note#

Running not in jupyter environment

In plotly, for a seismic volume, - x means inline order - y means crossline order - z means time order

ni means the dimension size of inline / x
nx means the dimension size of crossline / y
nt means the dimension size of time / depth / z

class cigvis.vispyplot.Plot3DColorbar(save: bool = False, name: str = 'cbar.png', cmap: Any = None, clim: Any = None, discrete: bool = None, disc_ticks: Any = None, dpi_scale: float = None, label_str: str = None, label_color: Any = None, label_size: Any = None, tick_size: Any = None, border_width: Any = None, border_color: Any = None, preserve_alpha: bool = None)#

Bases: object

Options used when updating/saving colorbars in plot3D.

border_color: Any = None#

border_width: Any = None#

clim: Any = None#

cmap: Any = None#

disc_ticks: Any = None#

discrete: bool = None#

dpi_scale: float = None#

label_color: Any = None#

label_size: Any = None#

label_str: str = None#

name: str = 'cbar.png'#

preserve_alpha: bool = None#

save: bool = False#

tick_size: Any = None#

class cigvis.vispyplot.Plot3DGui(enabled: bool = True, theme: str = 'dark')#

Bases: object

Options that control the optional PySide6 GUI shell in plot3D.

enabled: bool = True#

theme: str = 'dark'#

class cigvis.vispyplot.Plot3DSave(path: Any = None, directory: Any = None, transparent_bg: bool = True, bgcolor: Any = None)#

Bases: object

Options that control automatic screenshots in plot3D.

bgcolor: Any = None#

directory: Any = None#

path: Any = None#

transparent_bg: bool = True#

class cigvis.vispyplot.Plot3DView(size: Tuple[int, int] = (800, 600), show: bool = True, grid: Tuple[int, int] = None, share: bool = False, xyz_axis: bool = False, cbar_region_ratio: float = 0.125, bgcolor: Any = None, scale_factor: float = None, center: Any = None, fov: float = None, azimuth: float = None, elevation: float = None, zoom_factor: float = None, axis_scales: Tuple[float, float, float] = None, title: str = None, keys: str = None, shortcut_save_kw: Dict = None)#

Bases: object

Options that control the 3D view/canvas created by plot3D.

axis_scales: Tuple[float, float, float] = None#

azimuth: float = None#

bgcolor: Any = None#

cbar_region_ratio: float = 0.125#

center: Any = None#

elevation: float = None#

fov: float = None#

grid: Tuple[int, int] = None#

keys: str = None#

scale_factor: float = None#

share: bool = False#

shortcut_save_kw: Dict = None#

show: bool = True#

size: Tuple[int, int] = (800, 600)#

title: str = None#

xyz_axis: bool = False#

zoom_factor: float = None#

cigvis.vispyplot.add_mask(nodes: List, volume: List | ndarray, clim: List | Tuple = None, cmap: str | Dict = None, interpolation: str = 'linear', alpha=None, excpt=None, method: str = 'auto', texture_format: str = 'auto', preproc_func: Callable = None, *, clims: List | Tuple = None, cmaps: str | Dict = None, preproc_funcs: Callable = None, **kwargs) → List#

Add Mask/Overlay volumes

Parameters#

nodes: List[Node]: A List that contains AxisAlignedImage (may be created by create_slices)
volumearray-like or dict: 3D foreground volume/mask, or an axis source dict such as {'x': iline_source, 'y': xline_source, 'z': time_source}. Each source value may also be a spec such as {'data': time_source, 'axes': ('z', 'y', 'x')}. Add multiple masks by calling add_mask repeatedly.
climList: [vmin, vmax] for foreground slices plotting
cmapstr, Dict, or Colormap: colormap for foreground slices. A dict such as {'x': 'Reds', 'z': 'Blues'} applies the mask only to those axes.
interpolationstr: interpolation method. If the values of the slices is discrete, we recommand set as ‘nearest’
alphafloat or List[float]: if alpha is not None, using colormap.fast_set_cmap to set cmap
excptNone or str: it could be one of [None, ‘min’, ‘max’, ‘ramp’]

Returns#

slices_nodesList: list of slice nodes

cigvis.vispyplot.create_Line_logs(*args, **kwargs)#: Deprecated alias for create_line_logs().

cigvis.vispyplot.create_arbitrary_line(path=None, anchor=None, data=None, volume=None, nodes=None, cmap='gray', clim=None, hstep=1, vstep=1, **kwargs)#

Create an arbitrary line mesh node. You can pass one of path or anchor to define the arbitrary line path in X-Y pane. You also need to pass one of data or volume to define arbitrary line values, and if data is None, will interpolate from volume. To show the arbitrary line, you need pass cmap, clim to define the colors. You can also pass nodes, we will use the cmap and clim of AxisAlignedImage in nodes to define the colors, and the cmap, clim will be ignore.

Parameters#

patharray-like: The path of the arbitrary line, shape is like (N, 2)
anchorarray-like: The anchor of the arbitrary line, shape is like (m, 2), this can be view as the turning endpoints of a folded line. We will interpolate the path between the anchor points.
dataarray-like: The values of the arbitrary line, shape is like (N, nt)
volumearray-like: The 3D volume, shape is like (ni, nx, nt), if data is None, will interpolate from volume
nodesList: The nodes to get the cmap and clim to define the colors
cmapstr: The colormap for the arbitrary line
climList: The clim for the arbitrary line
hstepint: The horizontal step for the vertices of the arbitrary line mesh
vstepint: The vertical step for the vertices of the arbitrary line mesh

cigvis.vispyplot.create_axis(shape, mode='box', axis_pos=[3, 3, 1], north_direction=None, tick_nums=7, ticks_font_size=18, labels_font_size=20, intervals=[1, 1, 1], starts=[0, 0, 0], axis_labels=['Inline', 'Xline', 'Time'], north_scale=2, **kwargs)#

3D axis with ticks and labels.

Parameters#

shapetuple: The bound of the 3D world
modestr: The mode of the axis, ‘box’ or ‘axis’
axis_poslist or str: Which axis to show ticks? axis_pos can be set as ‘auto’ or a List. If is a List, for each axis, it can be 0, 1, 2, 3, representing the starting point of the ticks along the axis. 0: For ‘x’ axis -> (0, 0, 0), for ‘y’ axis -> (0, 0, 0), for ‘z’ axis -> (0, 0, 0) 1: For ‘x’ axis -> (0, 0, nz), for ‘y’ axis -> (0, 0, nz), for ‘z’ axis -> (0, ny, 0) 2: For ‘x’ axis -> (0, ny, 0), for ‘y’ axis -> (nx, 0, 0), for ‘z’ axis -> (nx, 0, 0) 3: For ‘x’ axis -> (0, ny, nz), for ‘y’ axis -> (nx, 0, nz), for ‘z’ axis -> (nx, ny, 0)
north_directionlist: The direction of the north, if not None, will create a NorthPointer
tick_numsint: The number of ticks on each axis
ticks_font_sizeint: The font size of the ticks
labels_font_sizeint: The font size of the labels
intervalslist: The sample intervals of the axis
startslist: The first sample of the axis
samplingslist[np.ndarray]: The sample points of the axis, default is None
axis_labelslist: The labels of the axis

cigvis.vispyplot.create_bodies(volume: ndarray, level: float, margin: float = None, color: str = 'yellow', filter_sigma: float | List = None, shading: str = 'smooth', dyn_light: bool = True, **kwargs) → List#

using marching_cubes to find meshs (its vertices and faces), and the then use vispy.scene.visuals.Mesh to show them

Parameters#

volumearray-like: 3D array
levelfloat: mesh value
colorstr: color for mesh
marginfloat: if is not None, set a margin to the volume
filter_sigmafloat: if is not None, filter the volume by gaussian filter
shadingstr: could be one of [‘smooth’, ‘flat’, None], if None, no shading filter
dyn_lightbool: dynamic light or not, valid when shading is not None
kwargsDict: parameters for vispy.scene.visuals.Mesh

cigvis.vispyplot.create_bodys(*args, **kwargs) → List#: Deprecated alias for create_bodies().

cigvis.vispyplot.create_colorbar(cmap, clim: List, discrete: bool = False, disc_ticks: List | Dict = None, label_str: str = '', preserve_alpha: bool = False, **kwargs) → Colorbar#

create a Colorbar instance. To draw colorbar, must spacify size params or call colorbar.update_size(size) function.

Parameters#

cmapstr: colormap
climList: [vmin, vmax] to norm
discretebool: draw a discrete colorbar or not
disc_ticksList or Dict: contains 2 elements, [values, ticklabels] or {‘value’: values, ‘labels’: labels}. values are used to get colors from cmap, ticklabels are the labels of colors
label_strstr: colorbar label
preserve_alphabool, optional: Keep cmap alpha in the colorbar if True. The default draws colorbar colors opaque.
kwargsDict: params for Colorbar

cigvis.vispyplot.create_colorbar_from_nodes(nodes, label_str='', select='auto', idx=0, idx2=0, preserve_alpha: bool = False, **kwargs)#

nodesList: List of nodes
selectstr: One of ‘auto’, ‘last’, ‘slices’, ‘mask’, ‘surface’, ‘logs’, ‘fault_skin’, ‘line_logs’. If ‘auto’, select ‘mask’ > ‘surface’ > ‘slices’ > ‘logs’ > ‘line_logs’ > ‘mesh’. If ‘last’, select the node[-1]
idxint: If there are multiple select nodes, select the idx-th node. If only one, ignore this parameter.
idx2int: If there are multiple cmap and clim for a node, select the idx2-th cmap and clim. If only one, ignore this parameters. This parameter is only used when select is ‘surface’ and ‘logs’
preserve_alphabool, optional: Keep cmap alpha in the colorbar if True. The default draws colorbar colors opaque.
kwargsDict: Other params for Colorbar.

cigvis.vispyplot.create_fault_skin(skin_dir, suffix='*', endian='>', values_type='likelihood', cmap='jet', clim=None, shading='smooth', dyn_light=True, **kwargs)#

cigvis.vispyplot.create_line_logs(logs: List | ndarray, value_type: str = 'depth', cmap: str = 'jet', clim: List = None, width: float = 6.0, return_cbar: bool = False, cbar_kw: Dict = None, **kwargs)#

create Line nodes to plot logs data

Parameters#

logsList or array-like: List (multi-logs) or np.ndarray (one log). For a log, its shape is like (N, 3) or (N, 4) or (N, 6) or (N, 7), the first 3 columns are (x, y, z) coordinates. If 3 columns, use the third column (z) as the color value (mapped by cmap), if 4 columns, the 4-th column is the color value (mapped by cmap) when value_type is not ‘depth’, if 6 or 7 columns, colors are RGB or RGBA format when value_type is not ‘depth’.
value_typestr: ‘depth’ or ‘amp’, if ‘depth’, force the colors are mapped by ‘depth’ (z or 3th column).
cmapstr: colormap
climList: [vmin, vmax] for showing
widthfloat: Line width
return_cbarbool: return a colorbar
kwargsDict: parameters for vispy.scene.visuals.Line

cigvis.vispyplot.create_overlay(bg_volume: ndarray, fg_volume: ndarray, pos: List | Dict = None, bg_clim: List = None, fg_clim: List = None, bg_cmap: str = 'Petrel', fg_cmap: str = None, bg_interpolation: str = 'cubic', fg_interpolation: str = 'cubic', return_cbar: bool = False, cbar_type: str = 'fg', **kwargs) → List#

Deprecated overlay API.

Use create_slices(bg_volume) followed by add_mask(...).

cigvis.vispyplot.create_point_cloud(points: ndarray, values: ndarray = None, cmap: str = 'viridis', clim: List = None, color=None, colors: ndarray = None, size: float = 4.0, symbol: str = 'o', edge_color=None, edge_width: float = 0, max_points: int = None, seed: int = 0, depth_test: bool = True, depth_mask: bool = True, blend: bool = False, **kwargs)#

Create a lightweight VisPy marker point-cloud node.

Parameters#

pointsarray-like: Point positions. Shape can be (N, 3), (N, 4) with scalar values in the last column, or (N, 6)/(N, 7) with RGB/RGBA colors in the trailing columns.
valuesarray-like, optional: Per-point scalar values mapped by cmap and clim.
color, colorsoptional: A single color, or per-point RGB/RGBA colors.
sizefloat: Marker size in screen pixels.
max_pointsint, optional: Randomly subsample points before upload.

Returns#

nodesList: A one-item list containing a Markers node, or an empty list when no points are provided.

cigvis.vispyplot.create_points(points: ndarray, r: float = 2, color: str = 'green', cmap='jet', clim=None, shading='flat', dyn_light=True, **kwargs)#

create a node to show points using Mesh instead of Marker

Parameters#

pointsarray-like: points, shape is like (N, 3).
rfloat: the radius of a point, to control the size of a point
colorstr: color to fill
cmapstr: colormap to map when set vertex_values
climList: clim if use cmap
shadingstr: could be one of [‘smooth’, ‘flat’, None], if None, no shading filter
dyn_lightbool: dynamic light or not, valid when shading is not None
kwargsDict: parameters for Mesh

cigvis.vispyplot.create_slices(volume: ndarray, pos: List | Dict = None, clim: List = None, cmap: str = 'Petrel', interpolation: str = 'cubic', texture_format=None, display_range: Dict = None, intersection_lines: bool = True, line_color=(1, 1, 1), line_width=2.0, **kwargs) → List#

create a slice node

Parameters#

volumearray-like or dict: 3D array, or an axis source dict such as {'x': iline_source, 'y': xline_source, 'z': time_source}. Each source value may also be a spec such as {'data': time_source, 'axes': ('z', 'y', 'x')}.
posList or Dict: init position of the slices, can be a List or Dict, such as: ` pos = [0, 0, 200] # x: 0, y: 0, z: 200 pos = [[0, 200], [9], []] # x: 0 and 200, y: 9, z: None pos = {'x': [0, 200], 'y': [1], z: []} `
climList: [vmin, vmax] for plotting
cmapstr or Colormap: colormap, it can be str or matplotlib’s Colormap or vispy’s Colormap
interpolationstr: interpolation method. If the values of the volume is discrete, we recommand set as ‘nearest’
texture_formatNone or ‘auto’,: if use None, the NaNs will be clip to clim[1], and if use ‘auto’, the NaNs will be discarded, i.e., transparent
display_rangeDict: optional display ranges in original data coordinates, such as {'z': (0, 900)}. Values are Python half-open ranges [start, stop).
line_colorTuple: color for intersection lines and border lines, default is white
line_widthfloat: width for intersection lines and border lines, default is 2.0
kwargsDict: internal slice provider options

Returns#

slices_nodesList: list of slice nodes

cigvis.vispyplot.create_splats(pos: ndarray, values: ndarray = None, cmap: str = 'viridis', clim: List = None, color=None, size=None, mode: str = 'surface', scaling: str = None, alpha: float = None, sigma_rel: float = None, cutoff: float = None, antialias: float = 1.0, canvas_size_limits: Tuple[float, float] = None, max_points: int = None, seed: int = 0, premultiply: bool = True, depth_test: bool = True, depth_mask: bool = None, **kwargs) → List#

Create a Gaussian splat node from point positions.

This is a user-facing wrapper around cigvis.vispynodes.Splat. mode chooses practical defaults so callers usually only need positions plus either values/cmap or a fixed color.

Parameters#

posarray-like: Point positions, shape (N, 2) or (N, 3).
valuesarray-like, optional: Per-point scalar values mapped through cmap.
cmap, clim: Colormap and limits used when values is provided.
colorcolor or array-like, optional: Fixed or per-point RGBA colors. If supplied, it overrides values/cmap coloring.
sizefloat or array-like, optional: Splat diameter. Defaults depend on mode.
mode{‘point’, ‘surface’, ‘volume’}: Preset for common use cases.
max_pointsint, optional: Randomly subsample points before upload.

Returns#

nodesList: A one-item list containing the Splat node, or an empty list when no points are provided.

cigvis.vispyplot.create_surfaces(surfs: List[ndarray], volume: ndarray = None, value_type: str = 'depth', clim: List = None, cmap: str = 'jet', shape: Tuple | List = None, interp: bool = False, quad: bool = False, quad_size: float | Tuple | List = 1.0, step1: int = 1, step2: int = 1, shading: str = 'smooth', dyn_light: bool = True, **kwargs) → List#

create a surfaces node

Parameters#

surfsList or array-like: the surface position, which can be an array (one surface) or List (multi-surfaces). Each surf can be a (n1, n2) array or (N, 3) array, such as >>> surf.shape = (n1, n2) # surf[i, j] means z pos at x=i, y=j >>> surf.shape = (N, 3) # surf[i, :] means i-th point position
volumearray-like: 3D array, values when surf_color is ‘amp’
value_typeList of str or ArrayLike: ‘depth’ for showing z, ‘amp’ for displaying amplitude of volume, or an array-like for values
climList: [vmin, vmax] of surface volumes
cmapstr or Colormap: cmap for surface
shapeList or Tuple: If surf’s shape is like (N, 3), shape must be specified, if surf’s shape is like (n1, n2), shape will be ignored
interpbool: interpolate the surface or not if the surf is not dense
quadbool: If True, treat each (N, 3) input point as a separate x-y aligned quad patch instead of interpolating/connecting points into a grid. This is useful for sparse or incomplete gentle horizons.
quad_sizefloat or tuple: Full side length of each quad patch when quad=True. A scalar creates square patches; a two-element tuple controls x/y size.
step1int: mesh interval in x direction
step2int: mesh interval in y direction
shadingstr: could be one of [‘smooth’, ‘flat’, None], if None, no shading filter
dyn_lightbool: dynamic light or not, valid when shading is not None

cigvis.vispyplot.create_well_logs(points: ndarray, values: ndarray = None, cmap: str | List = 'jet', cyclinder: bool = True, radius_tube: float | List = 1.5, radius_line: List = [2.2, 5], null_value: float = None, clim: List = None, index: List = None, tube_points: int = 16, mode: str = 'triangles', shading: str = 'smooth', dyn_light: bool = True, **kwargs)#

create a well log node

Parameters#

pointsarray-like: points positions, shape as (N, 3)
valuesarray-like: log curves, shape as (N, m), m curves
cmapList or str: colormaps for each curves
cyclinderbool: a cyclinder with a same radius or not
radius_tubefloat or List: if cyclinder, it’s a float, otherwise a List: [min_radius, max_radius]
radius_lineList: the log curves face radius
null_valuefloat: null value of log curves
climList: [[vmin1, vmax1], [vmin2, vmax2], …] for log curves
indexList: point index of each log curve attached to
tube_pointsint: the number of points to represent a circle
modestr: use ‘triangles’
shadingstr: could be one of [‘smooth’, ‘flat’, None], if None, no shading filter
dyn_lightbool: dynamic light or not, valid when shading is not None

Returns#

nodeList: List of a WellLog

Plot 3D vispy nodes.

New code should group options by ownership:

>>> cigvis.plot3D(
...     nodes,
...     view=cigvis.Plot3DView(
...         size=(900, 700),
...         grid=(1, 2),
...         share=True,
...         xyz_axis=False,
...         bgcolor='white',
...     ),
...     save=cigvis.Plot3DSave(
...         path='example.png',
...         transparent_bg=True,
...     ),
...     cbar=cigvis.Plot3DColorbar(save=False),
...     gui=cigvis.Plot3DGui(enabled=True, theme='dark'),
... )

Plain dicts are also accepted for view/save/cbar/gui. Automatic PNG saves capture the visible canvas framebuffer, the same path used by the s keyboard shortcut.

Legacy top-level parameters such as size=, savename=, grid=, layout={...}, and canvas={...} are still recognized for now, but they emit a migration warning. Unknown loose **kwargs now raise an error because they are ambiguous.

cigvis.vispyplot.run()#

cigvis.vispyplot.set_surface_color_by_slices_nodes(nodes, volumes)#