Matplotlib2DViewer¶

Aliases:

petres.viewers.Viewer2D

class petres.viewers.Matplotlib2DViewer[source]¶

Bases: Base2DViewer

Render 2D reservoir objects with Matplotlib.

This viewer manages a Matplotlib figure/axes pair, applies a reusable visual theme, and provides convenience methods to plot horizons, zones, and boundary polygons on a common 2D canvas.

Parameters:

fig (Figure or None, default=None) – Figure instance to use. If provided without ax, a new subplot is created on this figure.
ax (Axes or None, default=None) – Axes instance to use. If provided without fig, the corresponding ax.figure is used automatically.
theme (Matplotlib2DViewerTheme or None, default=None) – Theme configuration controlling layout and styling. When None, the default Matplotlib2DViewerTheme is used.
window_title (str, default='Petres 2D Viewer') – Window title shown in the figure manager (if supported by the Matplotlib backend).

Raises:

ValueError – If both fig and ax are provided but ax does not belong to fig.

Initialize a Matplotlib 2D viewer.

__init__(fig=None, ax=None, theme=None, window_title='Petres 2D Viewer')[source]¶

Initialize a Matplotlib 2D viewer.

set_theme(theme)[source]¶

Set the active viewer theme.

Parameters:: theme (Matplotlib2DViewerTheme) – Theme object containing visual settings such as figure size, axis labels, and grid behavior.

apply_theme()[source]¶

Apply the active theme values to the current axes.

set_window_title(title)[source]¶

Set the window title shown in the figure manager (if supported by the Matplotlib backend).

Parameters:: title (str) – Title text to set for the figure window.

show(*, title=None)[source]¶

Autoscale, style, and display the current figure.

Parameters:: title (str or None, default=None) – Optional title text shown above the axes.

add_horizon(horizon, *, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, **kwargs)[source]¶

Add a horizon map to the 2D axes.

The method resolves/derives 1D vertex coordinates, samples the horizon on the resulting grid, and forwards the scalar map to the surface layer.

Parameters:

horizon (Horizon) – Horizon instance to render.
x (ndarray or None, default=None) – 1D x-vertex coordinates. Mutually exclusive with xlim/ni/dx.
y (ndarray or None, default=None) – 1D y-vertex coordinates. Mutually exclusive with ylim/nj/dy.
xlim (tuple[float, float] or None, default=None) – Inclusive x-bounds used to generate vertices when x is not provided.
ylim (tuple[float, float] or None, default=None) – Inclusive y-bounds used to generate vertices when y is not provided.
ni (int or None, default=None) – Number of x-direction cells used with xlim.
nj (int or None, default=None) – Number of y-direction cells used with ylim.
dx (float or None, default=None) – X cell size used with xlim as an alternative to ni.
dy (float or None, default=None) – Y cell size used with ylim as an alternative to nj.
**kwargs (Any) – Additional keyword arguments forwarded to the surface plotting helper.

Returns:

The viewer instance (for chaining).

Return type:

Matplotlib2DViewer

Raises:

ValueError – If vertex resolution arguments are inconsistent.

Examples

>>> viewer = Matplotlib2DViewer()
>>> viewer.add_horizon(horizon, xlim=(0, 500), ylim=(0, 400), ni=100, nj=80, cmap="viridis").show()

add_zone(zone, *, x=None, y=None, xlim=None, ylim=None, ni=None, nj=None, dx=None, dy=None, mode='thickness', **kwargs)[source]¶

Add a zone scalar map to the 2D axes.

The method samples the zone top/base surfaces on a resolved grid and plots either top, base, or absolute thickness values.

Parameters:

zone (Zone) – Zone instance to render.
x (ndarray or None, default=None) – 1D x-vertex coordinates. Mutually exclusive with xlim/ni/dx.
y (ndarray or None, default=None) – 1D y-vertex coordinates. Mutually exclusive with ylim/nj/dy.
xlim (tuple[float, float] or None, default=None) – Inclusive x-bounds used to generate vertices when x is not provided.
ylim (tuple[float, float] or None, default=None) – Inclusive y-bounds used to generate vertices when y is not provided.
ni (int or None, default=None) – Number of x-direction cells used with xlim.
nj (int or None, default=None) – Number of y-direction cells used with ylim.
dx (float or None, default=None) – X cell size used with xlim as an alternative to ni.
dy (float or None, default=None) – Y cell size used with ylim as an alternative to nj.
mode ({'top', 'base', 'thickness'}, default='thickness') – Which scalar field to plot.
**kwargs (Any) – Additional keyword arguments forwarded to the surface plotting helper.

Returns:

The viewer instance (for chaining).

Return type:

Matplotlib2DViewer

Raises:

ValueError – If mode is not one of 'top', 'base', or 'thickness'.

Examples

>>> Matplotlib2DViewer().add_zone(zone, x=[0, 50], y=[0, 50], mode="top", cmap="cividis").show()

add_boundary_polygon(boundary, *, facecolor='#7ec8e3', edgecolor='#1f2937', linewidth=1.8, alpha=0.3, show_fill=True, show_vertices=False, vertex_color=None, vertex_size=24.0, show_label=False, label=None, label_fontsize=10.0, label_box=True, pad_ratio=None, **kwargs)[source]¶

Add a boundary polygon overlay to the 2D axes.

Parameters:

boundary (BoundaryPolygon) – Polygon to draw.
facecolor (str or tuple[float, float, float] or tuple[float, float, float, float], default='#7ec8e3') – Fill color for the polygon.
edgecolor (str or tuple[float, float, float] or tuple[float, float, float, float], default='#1f2937') – Edge color.
linewidth (float, default=1.8) – Boundary line width.
alpha (float, default=0.30) – Fill opacity (0–1).
show_fill (bool, default=True) – Whether to fill the polygon.
show_vertices (bool, default=False) – Whether to show vertex markers.
vertex_color (str or tuple[float, float, float] or tuple[float, float, float, float] or None, default=None) – Color for vertex markers; defaults to edgecolor.
vertex_size (float, default=24.0) – Marker size for vertices.
show_label (bool, default=True) – Whether to render the polygon name/label.
label (str or None, default=None) – Custom label text; defaults to boundary.name.
label_fontsize (float, default=10.0) – Font size for the label.
label_box (bool, default=True) – Whether to draw a small background box behind the label.
pad_ratio (float or None, default=None) – Padding fraction applied to axis limits; defaults to theme margins.
**kwargs (Any) – Additional keyword arguments forwarded to the patch helper.

Returns:

The viewer instance (for chaining).

Return type:

Matplotlib2DViewer

Examples

>>> viewer = Matplotlib2DViewer()
>>> viewer.add_boundary_polygon(boundary, show_vertices=True, vertex_size=30).show()

add_wells(wells, *, marker='o', marker_size=56.0, marker_color='#b91c1c', marker_edgecolor='white', marker_edgewidth=0.9, show_label=True, label=None, label_fontsize=9.5, label_color='#111827', label_offset=(6.0, 6.0), zorder=5.0, **kwargs)[source]¶

Add vertical wells to the 2D axes as markers with optional labels.

Parameters:

wells (VerticalWell or Sequence[VerticalWell]) – Single well or sequence of wells to plot.
marker (str, default='o') – Marker style used for each well.
marker_size (float, default=56.0) – Marker size in points^2.
marker_color (Any, default='#b91c1c') – Marker face color.
marker_edgecolor (Any, default='white') – Marker edge color.
marker_edgewidth (float, default=0.9) – Marker edge line width.
show_label (bool, default=True) – Whether to render labels for wells.
label (str or None, default=None) – Optional fixed label text for all wells; defaults to each well name.
label_fontsize (float, default=9.5) – Label text size.
label_color (Any, default='#111827') – Label color.
label_offset (tuple[float, float], default=(6.0, 6.0)) – Label offset in points from marker center.
zorder (float, default=5.0) – Base drawing order for well marker/label.
**kwargs (Any) – Extra keyword arguments forwarded to Matplotlib Axes.scatter.

Returns:

The viewer instance (for chaining).

Return type:

Matplotlib2DViewer

Raises:

TypeError – If wells is not a VerticalWell or a sequence of them.