---

name: grids-and-visualization description: "Enables GemPy grid selection, coordinate evaluation, topography and section setup, and optional 2-D or 3-D visual inspection of computed geological models." disable-model-invocation: true metadata: disco-role: operating license: EUPL 1.2

Grids and visualization

Use this route when the task is to choose where GemPy evaluates a model, query specific coordinates, add sections or topography, or inspect an already-built model. The model must already have valid extents and structural data; route model creation, input tables, and compute ordering to the modeling/data sub-skills. This route does not own mesh extraction, topology, gravity, or model persistence.

Fast route

1. Inspect the existing grid before changing it:

   grid = model.grid
   print(grid.active_grids)
   print(grid.extent)                         # [xmin, xmax, ymin, ymax, zmin, zmax]
   print(grid.values.shape)
   if grid.regular_grid is not None:
       print(grid.regular_grid.resolution)
   

2. Choose one or more grid types and configure them before gempy.compute_model(model). Grid setters activate their new grid, but do not remove previously active grids unless reset=True is used.

3. Recompute after any grid change. Results for custom, section, topography, and centered points are not populated by merely constructing the grid.

4. Validate shape and active flags before plotting. Run the safe bundled check for a package/import/grid-only diagnostic: scripts/grid_smoke.py.

5. Use gempy_viewer.plot_2d or plot_3d only when the optional viewer and its rendering dependencies are available. Use show=False for compositing or headless-friendly construction; use image=True for an off-screen 3-D render. Route installation/display failures to the environment and troubleshooting sub-skill.

For detailed signatures and coordinate conventions read references/grid-reference.md. For plotting recipes read references/visualization-workflows.md. For failures read references/troubleshooting.md.

Select a grid

• Dense regular grid: pass resolution=[nx, ny, nz] when creating the model. model.grid.regular_grid is the RegularGrid; its values are cell-center coordinates and normally contain nx * ny * nz points.

• Octree grid: creation with no explicit resolution uses the model's octree grid and refinement options. Do not assume its point count is a dense nx * ny * nz block. This route only inspects/selects it; octree tuning and mesh work belong to modeling/advanced routes.

• Custom grid:

  import numpy as np
  import gempy as gp
  
  query_xyz = np.asarray([[1000., 1000., 700.],
                          [1000., 1000., 400.]], dtype=float)
  gp.set_custom_grid(model.grid, query_xyz)
  gp.compute_model(model)
  values = model.solutions.raw_arrays.custom
  

  query_xyz must be an (n, 3) array in the same world coordinate system as the model extent. Returned custom values preserve the input row order.

• Centered grid: use gp.set_centered_grid(grid, centers, resolution, radius) for points concentrated around one or more centers. centers is (n, 3); resolution is a three-component sequence; radius is a scalar or three-component sequence. This route configures the grid only; gravity kernels and geophysical inputs belong to the advanced route.

Sections and topography

A section dictionary maps each stable section name to ((x_start, y_start), (x_stop, y_stop), (n_horizontal, n_vertical)):

gp.set_section_grid(model.grid, {
    "section_SW_NE": ((250., 250.), (1750., 1750.), (100, 80)),
    "section_NW_SE": ((250., 1750.), (1750., 250.), (100, 80)),
})

The endpoints are world X/Y coordinates; the section spans the regular grid's Z extent. Names are retained in insertion order and are the names passed to plot_2d(..., section_names=[...]). Inspect model.grid.sections.df, .names, .resolution, and .get_section_grid(name) before plotting.

Topography APIs are:

• gp.set_topography_from_random(grid, fractal_dimension=2.0, d_z=None, topography_resolution=None) for a synthetic surface. A supplied resolution should be [nx, ny] with values at least 2; d_z controls the elevation range. It uses the model XY extent and activates TOPOGRAPHY.
• gp.set_topography_from_arrays(grid, xyz_vertices) for an (n, 3) XYZ vertex cloud. GemPy interpolates those vertices onto the regular grid's XY lattice; this path requires SciPy.
• gp.set_topography_from_file(grid, filepath, crop_to_extent=None) for a structured topography reader. This path requires the optional subsurface package and a reader-supported file. Do not use the unimplemented GDAL or singular-array stubs as a fallback.

Topography and sections are grid data, not merely viewer overlays. Activate both before computing when their results are needed. Plot a geological map with section_names=["topography"] after topography has been configured and the model has been computed.

Active-grid discipline

Grid.GridTypes is a flag set: OCTREE, DENSE, CUSTOM, TOPOGRAPHY, SECTIONS, and CENTERED. gp.set_active_grid(grid, grid_type=[...], reset=False) ORs requested flags into the current set. Use reset=True to replace the active selection deliberately:

# Keep only the dense grid for a baseline recomputation.
gp.set_active_grid(model.grid, [model.grid.GridTypes.DENSE], reset=True)

# Add a section and topography to the currently selected base grid.
gp.set_active_grid(model.grid,
                   [model.grid.GridTypes.DENSE,
                    model.grid.GridTypes.SECTIONS,
                    model.grid.GridTypes.TOPOGRAPHY],
                   reset=True)

Do not infer the result array from the last setter. grid.values is a concatenation of every active grid's coordinates, and a compute call evaluates all of them. Before and after a compute, log active_grids, each component's length, and the relevant solutions.raw_arrays member. If a prior custom or section grid remains active, a dense-shaped result can be unexpectedly longer than the dense grid alone. Always recompute after resetting flags.

Evaluate arbitrary coordinates

For a one-off coordinate evaluation, use gp.compute_model_at(model, at) with an (n, 3) NumPy array. It returns the computed values for those rows, but intentionally installs a custom grid, resets the active selection to CUSTOM, and computes the model. Save old_flags = model.grid.active_grids before the call and restore them afterward with model.grid.active_grids = old_flags (or an explicit set_active_grid(..., reset=True)), then recompute if subsequent work expects the old grid solutions. This side effect is part of the public API; do not treat compute_model_at as a read-only probe.

Viewer boundary

gempy_viewer is optional from this route's perspective. A 2-D plot uses Matplotlib and can return a Plot2D object whose .axes can be customized; 3-D plotting returns a viewer object wrapping a PyVista plotter. Viewer calls require a computed model for lithology/scalar results, while input-only views may be useful before computation. See the visualization reference for direction, position, cell_number, named sections, scalar fields, headless construction, and output expectations.