wolfhece.wolf_array._base_gui

GUI-enabled WolfArray with OpenGL rendering and wxPython integration.

This module defines WolfArray, which inherits from WolfArrayModel (data operations) and Element_To_Draw (OpenGL / MapViewer integration). It adds:

• Multiple 2D rendering back-ends (display-list via Cython, per-cell shader, shared-resource shader).

• LOD (Level-Of-Detail) tiling for large grids.

• Interactive wx dialogs for crop, band selection, volume estimation, etc.

• Palette / colormap management with automatic isopop.

• 3D preview support.

Author: HECE - University of Liege, Pierre Archambeau Date: 2024

Copyright (c) 2024 University of Liege. All rights reserved.

This script and its content are protected by copyright law. Unauthorized copying or distribution of this file, via any medium, is strictly prohibited.

Module Contents

wolfhece.wolf_array._base_gui.msg = 'Error importing OpenGL library'

class wolfhece.wolf_array._base_gui.WolfArray(fname: str = None, mold: wolfhece.wolf_array._base.WolfArrayModel = None, masknull: bool = True, crop: list[list[float], list[float]] = None, whichtype=WOLF_ARRAY_FULL_SINGLE, preload: bool = True, create: bool = False, mapviewer=None, nullvalue: float = 0.0, srcheader: wolfhece.wolf_array._header_wolf.header_wolf = None, idx: str = '', plotted: bool = False, need_for_wx: bool = False, mask_source: numpy.ndarray = None, np_source: numpy.ndarray = None)

Bases: wolfhece.wolf_array._base.WolfArrayModel, wolfhece.drawing_obj.Element_To_Draw

GUI-enabled WolfArray with OpenGL rendering and wxPython integration.

Inherits all data operations from WolfArrayModel and adds:

• OpenGL 2D rendering via display-lists (Cython wolfogl) or GLSL shaders (WolfArrayShader2D).

• LOD tiling: the grid is divided into tiles whose resolution adapts to the current zoom level.

• Palette / colormap management with automatic isopop adjustment.

• Interactive wx dialogs for crop, band selection, volume estimation, file saving, and error reporting.

• Ops_Array integration for the GUI operations panel.

• 3D preview via WolfArrayPlotShader.

myops: wolfhece.ui.wolf_array_ops.Ops_Array

_clip_zones: list[wolfhece.wolf_array._clipping.WolfArrayClipZone] = []

_clip_show_bars: bool = True

property rendering_machine: wolfhece.wolf_array._base.OGLRenderer

Current OpenGL rendering back-end (OGLRenderer).

property clip_zones: list[wolfhece.wolf_array._clipping.WolfArrayClipZone]

Active clip zones restricting OpenGL rendering.

add_clip_zone(clip: wolfhece.wolf_array._clipping.WolfArrayClipZone) → wolfhece.wolf_array._clipping.WolfArrayClipZone

Add a clip zone to restrict rendering.

Parameters:

clip – The clip zone to add.

Returns:

The same clip zone (for chaining).

remove_clip_zone(clip: wolfhece.wolf_array._clipping.WolfArrayClipZone)

Remove a previously added clip zone.

clear_clip_zones()

Remove all clip zones (rendering becomes unrestricted).

add_clip_zone_from_bounds(xmin: float, ymin: float, xmax: float, ymax: float, active: bool = True) → wolfhece.wolf_array._clipping.WolfArrayClipZone

Create and add a clip zone from world-coordinate bounds.

Returns:

The newly created clip zone.

add_clip_zone_from_header(h: wolfhece.wolf_array._header_wolf.header_wolf, active: bool = True) → wolfhece.wolf_array._clipping.WolfArrayClipZone

Create and add a clip zone from a header_wolf.

Returns:

The newly created clip zone.

setup_curtain_clip(edge: wolfhece.wolf_array._clipping.ClipSliderEdge = ClipSliderEdge.RIGHT, **slider_kwargs) → tuple[wolfhece.wolf_array._clipping.WolfArrayClipZone, wolfhece.wolf_array._clipping.ClipSlider]

Set up a “curtain” clip with a draggable slider.

Creates a clip zone covering the full array extent and attaches a slider on the given edge. This is the recommended entry point for the “swipe to compare” use case.

Parameters:

• edge – Which edge the slider bar controls.

• slider_kwargs – Extra keyword arguments forwarded to ClipSlider (e.g. color, line_width).

Returns:

(clip_zone, slider) tuple.

setup_vertical_band(**slider_kwargs) → tuple[wolfhece.wolf_array._clipping.WolfArrayClipZone, list[wolfhece.wolf_array._clipping.ClipSlider]]

Set up a vertical band with left and right sliders.

The left slider hides everything to its left, the right slider hides everything to its right.

Returns:

(clip_zone, [left_slider, right_slider]) tuple.

setup_horizontal_band(**slider_kwargs) → tuple[wolfhece.wolf_array._clipping.WolfArrayClipZone, list[wolfhece.wolf_array._clipping.ClipSlider]]

Set up a horizontal band with bottom and top sliders.

The bottom slider hides everything below, the top slider hides everything above.

Returns:

(clip_zone, [bottom_slider, top_slider]) tuple.

setup_clip_from_view(xmin: float, ymin: float, xmax: float, ymax: float, invert: bool = False) → wolfhece.wolf_array._clipping.WolfArrayClipZone

Create a clip zone matching the given viewport bounds.

Parameters:

invert – If True, the exterior of the zone is drawn.

Returns:

The created clip zone.

snapshot_clip_config(name: str) → wolfhece.wolf_array._clipping.ClipConfig

Create a ClipConfig snapshot of the current clip zones.

apply_clip_config(cfg: wolfhece.wolf_array._clipping.ClipConfig)

Apply a ClipConfig to this array, replacing current clips.

property epsg_parent: int

EPSG code of the parent map viewer.

Falls back to the array’s own EPSG when no viewer is attached.

_check_epsg_coherence()

Check whether the array and map viewer share the same EPSG code.

Returns:

True if both codes match, False otherwise.

Return type:

bool

property usemask

Whether the operations panel requests masked-value filtering.

Delegates to self.myops.usemask; returns False if no operations panel is attached.

set_opacity(alpha: float)

Set the global transparency of this array.

alpha is clamped to [0, 1]. If an Ops_Array panel is attached, the corresponding slider is synchronised.

Parameters:

alpha – Opacity value (0 = fully transparent, 1 = opaque).

Returns:

The clamped alpha value actually applied.

Return type:

float

extract_selection()

Create a new WolfArray from the current selection and add it to the map viewer with suffix '_extracted'.

prepare_3D()

Build a WolfArrayPlotShader for 3D rendering.

Converts the data to a GPU-ready z-texture (C-contiguous float32, masked cells set to array.min()) and creates a per-cell shader object stored in self._array3d.

show_properties()

Show the Ops_Array properties window (wxPython).

hide_properties()

Hide the Ops_Array properties window.

property Operations: wolfhece.ui.wolf_array_ops.Ops_Array

The Ops_Array instance managing GUI operations.

add_ops_sel()

Attach an Ops_Array panel and a selection manager.

• Creates an Ops_Array if a map viewer is available.

• Creates a SelectionData (or SelectionDataMB for multi-block arrays) if none exists yet.

change_gui(newparentgui)

Re-parent this array to a different WolfMapViewer.

If no viewer was previously attached, creates a new Ops_Array panel. Otherwise, migrates the existing one.

Parameters:

newparentgui – Target WolfMapViewer instance.

Raises:

AssertionError – If newparentgui is not a WolfMapViewer.

init_from_new(dlg: wolfhece.ui.wolf_array_ui.NewArray)

Initialise grid geometry from a completed NewArray dialog.

Reads dx, dy, nbx, nby, origx, origy from the dialog widgets and creates a ones-filled masked array.

Parameters:

dlg – The NewArray dialog that has been validated.

_prompt_crop(dx: float, dy: float) → list | None

Show a CropDialog and return crop bounds.

Parameters:

• dx – Cell size in X (pre-filled, read-only).

• dy – Cell size in Y (pre-filled, read-only).

Returns:

[[xmin, xmax], [ymin, ymax]] or None if cancelled.

_prompt_band_selection(band_names: list[str]) → int | None

Show a single-choice dialog for raster band selection.

Parameters:

band_names – List of human-readable band names.

Returns:

1-based band index, or None if cancelled.

_prompt_save_file(message: str, wildcard: str) → str | None

Show a file-save dialog.

Parameters:

• message – Dialog title / prompt.

• wildcard – File-type filter string (wx format).

Returns:

Selected file path, or None if cancelled.

_show_error_dialog(message: str)

Log an error and optionally show a wx error dialog.

Parameters:

message – Error message text.

volume_estimation(axs=None)

Interactive volume estimation driven by wx dialogs.

Prompts the user for Z-max, number of slices, and labelling method, then delegates to WolfArrayModel.volume_estimation().

Parameters:

axs – Optional matplotlib axes for plotting results.

Returns:

The result of WolfArrayModel.volume_estimation().

check_plot()

Enable plotting and lazy-load data if needed.

If the array has not been loaded yet (and a filename exists), reads all data from disk and applies the null-value mask. Updates the palette so that colour stops match the current data range.

uncheck_plot(unload: bool = True, forceresetOGL: bool = False, askquestion: bool = True)

Disable plotting and optionally unload data from memory.

Parameters:

• unload – If True (default), free the array data and OpenGL resources after prompting the user.

• forceresetOGL – If True, delete OpenGL lists without asking.

• askquestion – If True (default) and a wx App is running, prompt the user before unloading or resetting.

reset_plot(whichpal=0, mimic=True)

Reset OpenGL resources and rebuild the palette.

Deletes cached display lists / shader objects, clears any 2D/3D array caches, recomputes the palette, and propagates the reset to linked arrays when mimic is True.

Parameters:

• whichpal – Palette index passed to updatepalette().

• mimic – If True, also reset linked arrays sharing the same palette.

updatepalette(which: int = 0, onzoom=[])

Recompute palette colours for the current data range.

When which == 0 and VERSION_RGB >= 2, only the float32 temporary buffer is prepared (palette look-up is done on the GPU). When which == 1 or VERSION_RGB == 1, a full RGBA buffer (self.rgb) is computed on the CPU.

Parameters:

• which – 0 for normal update, 1 to force CPU-side RGBA computation (used by hillshade overlay).

• onzoom – Optional [xmin, xmax, ymin, ymax] window; if given, the iso-population palette is computed over this sub-extent only.

find_minmax(update=False)

Refresh the bounding-box cache.

This override of Element_To_Draw updates xmin/xmax/ymin/ymax from the grid header.

Parameters:

update – If True, recompute bounds from the header; otherwise leave the existing values untouched.

_get_LOD(sx: float, sy: float, xmin: float, ymin: float, xmax: float, ymax: float)

Determine the level-of-detail factor for the current viewport.

The LOD is the smallest power of two such that each cell occupies at least 0.5 screen pixels. A return value of 1 means every cell is drawn; higher values skip cells.

Parameters:

• sx – Horizontal scale (pixels per world-unit).

• sy – Vertical scale (pixels per world-unit).

• xmin – Viewport lower-left X.

• ymin – Viewport lower-left Y.

• xmax – Viewport upper-right X.

• ymax – Viewport upper-right Y.

Returns:

LOD factor (>= 1), or -1 if nothing is visible.

_get_dxdy_LOD(lod: int)

Return the effective cell sizes (dx, dy) at a given LOD.

Parameters:

lod – Level-of-detail factor.

Returns:

(dx * lod, dy * lod).

_get_scale_step_LOD(lod: int)

Return the tile step _gridsize * lod.

Parameters:

lod – Level-of-detail factor.

_get_grid_shape_LOD(lod: int)

Return (nbx, nby) of LOD tiles covering the full grid.

Parameters:

lod – Level-of-detail factor.

Returns:

Tuple (ceil(nbx / step), ceil(nby / step)).

_get_grid_LOD(lod: int, shader: bool = False)

Return (or create) the tile cache for a given LOD.

On first call for a given lod, allocates OpenGL display-list IDs (legacy path) or a WolfArrayPlotShader grid (shader path).

Parameters:

• lod – Level-of-detail factor.

• shader – If True, allocate shader objects instead of GL display-list IDs.

Returns:

dict with keys 'nbx', 'nby', 'cache', 'done'.

_get_part_to_plot_LOD(lod: int, xmin: float, ymin: float, xmax: float, ymax: float)

Compute the tile index range visible in the current viewport.

Parameters:

• lod – Level-of-detail factor.

• xmin – Viewport lower-left X.

• ymin – Viewport lower-left Y.

• xmax – Viewport upper-right X.

• ymax – Viewport upper-right Y.

Returns:

((istart, iend), (jstart, jend)) tile indices (inclusive).

_draw_2d_lists(sx: float, sy: float, xmin: float, ymin: float, xmax: float, ymax: float)

Draw the array using legacy OpenGL display lists.

Parameters:

• sx – Horizontal scale (pixels per world-unit).

• sy – Vertical scale (pixels per world-unit).

• xmin – Viewport lower-left X.

• ymin – Viewport lower-left Y.

• xmax – Viewport upper-right X.

• ymax – Viewport upper-right Y.

_fill_ogllist_for_one_grid_cell(lod, loci, locj, force=False)

Build the OpenGL display list for one LOD tile.

Delegates actual vertex generation to the Cython wolfogl helpers depending on VERSION_RGB and the array dtype.

Parameters:

• lod – Level-of-detail factor.

• loci – Tile column index.

• locj – Tile row index.

• force – If True, rebuild even if already built.

_get_xy_centers_LOD(lod: int, loci: int, locj: int, usenap: bool = True)

Compute cell-centre coordinates for one LOD tile.

Returns a flat float32 array of (x, y) pairs suitable for upload as a VBO.

Parameters:

• lod – Level-of-detail factor.

• loci – Tile column index.

• locj – Tile row index.

• usenap – If True (default), exclude masked (null) cells.

Returns:

1-D np.float32 array [x0, y0, x1, y1, …].

_fill_oglshader_for_one_grid_cell(lod, loci, locj, force=False)

Prepare one LOD tile for the per-cell shader pipeline.

Creates a WolfArrayPlotShader object containing the vertex buffer and z-texture for the tile.

Parameters:

• lod – Level-of-detail factor.

• loci – Tile column index.

• locj – Tile row index.

• force – If True, rebuild even if already built.

_draw_2d_shader(sx: float = None, sy: float = None, xmin: float = None, ymin: float = None, xmax: float = None, ymax: float = None)

Delegate 2D shader rendering to WolfArrayShader2D.

_cleanup_shader_2d_resources()

Release all shared GL resources for 2D shader rendering.

plot(sx: float = None, sy: float = None, xmin: float = None, ymin: float = None, xmax: float = None, ymax: float = None, size: float = None)

Draw the array in the current OpenGL context.

Dispatches to _draw_2d_shader() or _draw_2d_lists() depending on the active rendering backend. Also draws the current selection overlay and attached zones.

When clip_zones contains active zones, rendering is restricted to those regions via GL_SCISSOR_TEST. Each active zone triggers a separate rendering pass so that the union of all zones is visible. Attached ClipSlider bars are drawn afterwards (outside the scissor) for visual feedback.

Parameters:

• sx – Horizontal scale (pixels per world-unit).

• sy – Vertical scale (pixels per world-unit).

• xmin – Viewport lower-left X.

• ymin – Viewport lower-left Y.

• xmax – Viewport upper-right X.

• ymax – Viewport upper-right Y.

• size – Unused — kept for API compatibility with Element_To_Draw.

_plot_array_core(sx, sy, xmin, ymin, xmax, ymax)

Internal: dispatch to the active 2D rendering backend.

delete_lists()

Release all cached OpenGL display lists and shader objects.