`mrst-gui`: Graphical user-interfaces for MRST¶

Graphical interfaces for visualization of reservoir states and petrophysical data. The main gateway to this functionality is the plotToolbar function, which allows for easy visualization of simulation output with value thresholding, dynamic slicing/subset functionality and different transforms (logarithm, absolute value, nonzero values etc).

The module also includes utility routines for building interactive tools with MRST, making it easy to build tailored visualization suites for specific applications.

Contents¶

MRST-GUI

Files: addFilters - Filter cells based on dataset. colorizedHistogram - Undocumented Utility Function datasetSelector - Create dataset selector either as standalone or integrated in gui. editWells - Edit well setup editStructGUI - Undocumented Utility Function extractSubcellsInteractive - Extract a subset of cells from a grid interactively. fastRotateButton - Hook in faster rotation for 3D plots. getStructFields - Dump possible plotting fields of a struct into human readable format. interactiveSelection - logColorbar - Create colorbar for log dataset mrstFigure - Create or select figure with convenient default options for 3d plotting plotAdjustiblePlane - { plotCellVectorData - Plot a vector field defined per cell plotCurveTube - Plot a curve as a tube with variable width plotGridBarchart - Plot barcharts on top of grid for cell data plotToolbar - Plot one or more datasets with interactive tools for visualization plotWellData - { readStructField - Read a field from a struct. setRenderFixes - Set fixes which may reduce crashes in MATLAB plots. SummaryViewer - Simple summary viewer. Usage (name without extension) visualizeEclipseOutput - Simple, experimental Eclipse output visualization function.

plotToolbar¶

Plot one or more datasets with interactive tools for visualization

Synopsis:

h = plotToolbar(G, dataset)
h = plotToolbar(G, struct('data1', data, 'data2', data));

Description:

plotToolbar is designed to be a drop-in replacement for plotCellData which has several added features that allow the user to inspect and manipulate several datasets. The key features are:

Capable of interacting with multiple datasets simultanously. See

required parameters.

Supports all options supported by plotCellData.

Improved rotation speed of figures due to custom rotate handler.

This is extremely useful when working with 100k+ cells.

Subdivide model, use slicing planes to visualize internal

features or limit by logical indices or the values of datasets.

Dynamic histograms allow easy inspection of subsamples of a

complex dataset.

Multiple transformations (log10, absolute value etc) makes it

easy to explore a new dataset without any a priori knowledge of the data. Visualize directly on the equivialent logical grid structure.

Visualize a whole simulation, including playback with dynamic

selection.

Keyword Arguments:
Parameters:	Grid – Grid data structure. data – Scalar cell data with which to colour the grid. One scalar, indexed colour value for each cell in the grid or one TrueColor value for each cell. If a cell subset is specified in terms of the ‘cells’ parameter, ‘data’ must either contain one scalar value for each cell in the model or one scalar value for each cell in this subset. cells – Vector of cell indices defining sub grid. The graphical output of function ‘plotToolbar’ will be restricted to the subset of cells from ‘G’ represented by ‘cells’. If unspecified, function ‘plotToolbar’ will behave as if the user defined cells = 1 : G.cells.num meaning graphical output will be produced for all cells in the grid model ‘G’. If ‘cells’ is empty (i.e., if ISEMPTY(cells)), then no graphical output will be produced. 'pn'/pv – List of property names/property values. OPTIONAL. This list will be passed directly on to function PATCH meaning all properties supported by PATCH are valid.
	Most supported options correspond to activating buttons in the GUI at the first launch. This is useful when the user wants to specify the exact setup for the plotting window. log10 – Toggle default logarithm transform of data. exp – Toggle default exponential transform of data. abs – Toggle default absolute value transform of data. filterzero – Toggle filtering of near-zero values. outline – Toggle default outline of grid. pauseTime – Time to use between plot updates when interactive playback is used. lockCaxis – Toggle locking of caxis for dynamic playback. plot1d – Toggle 1D plotting (requires grid with only one dimension with more than one cell thickness) plotMarkers – Markers used for 1D plotting. Defaults to none. field – Initial field to plot. For multiple columns, the syntax ‘s:3’ is supported (take column 3 of matrix s). Must be a valid plotting field. startplayback – Start playback immediately with no user input.
Returns:	h – Handle to underlying plot call. If used interactively, this handle will not remain usable as this static value will not be updated when the plot changes.

Example:

G = cartGrid([10,10,10])
G = computeGeometry(G);
%Visualize the grid itself
plotToolbar(G, G)

See also

plotCellData, plotFaces

class SummaryViewer(smry)¶: Simple summary viewer. Usage (name without extension) >> SummaryViewer(readEclipseSummaryUnFmt([filepath, name]))

addFilters(G, filters, datasets, callback)¶

Filter cells based on dataset.

Synopsis:

addFilters(G, [], datasets, @(selection, filters) function)

DESCRIPTION:

Parameters:

G – Grid data structure.
filters – Filters emenating from previous call to addFilters.
datasets – Dataset which is to be filtered.
callback – Function handle accepting (active, filters) interface.
is a logical mask suitable for plotting based on the filters and (Active) –
a datastructure which allows filters to be reapplied in the (filters) –
gui. (same) –

Returns:

Nothing

Note

Internal function for use by plotToolbar. Subject to change.

See also

plotToolbar

colorizedHistogram(data, n_sample)¶: Undocumented Utility Function

datasetSelector(G, datasets, varargin)¶

Create dataset selector either as standalone or integrated in gui.

Synopsis:

% Select dataset and block until return
data = datasetSelector(G, datasets)

% Setup persistent selector with callback for integration with apps
datasetSelector(G, datasets, 'Parent', somehandle, 'Callback',
@callback)

Description:

This function spawns a dataset selector which allows valid plotting datasets to be selected. For instance, consider a state-object as defined by initState:

The fields of this struct may be: .s (Two columns of G.cells.num, suitable for plotting) .pressure (One column of G.cells.num length, suitable for plotting) .wellSol.pressure (Number of wells long column, not suitable for

plotting)

datasetSelector deduces that only .s and pressure are suitable for direct visualization, and presents these to the user. If multiple states are provided as a struct array, these can be selected as well.

Keyword Arguments:
Parameters:	G – Grid intended to visualization. datasets – A valid dataset. Either a input suitable for plotCellData directly, or a struct array of length 1 or more each containing one or more fields which are valid input for plotCellData, or have columns which are valid input for plotCellData.
	Location – Location supplied to parent gui for placement. Parent – Handle to gui component where the selector should be embedded. If not provided (default), will spawn own window. Setname – Name to use for dataset. Defaults to the inputname of the dataset, but this is not always meaningful with nested calls. Callback – Function handle of the form @(data, N, name) where data is input suitable for plotCellData, N is the index in the datasets array and name is the name of the dataset. Nofields – Disables selecting / checking fields. Implies that both data and name will be []. Tag – Tag to use for the panel containing the selector pauseTime – Time (in seconds) between updates to plot when used for dynamic playback. Note that this has no effect if the model is too complicated for Matlab to render at this rate.
Returns:	(OPTIONAL) Selected dataset.

Note

Behavior greatly dependent on number of output arguments. If output is requested, the function will block for selection and close afterwards, otherwise it will simply execute (possibly empty) callbback.

See also

plotToolbar

editStructGUI(data, varargin)¶: Undocumented Utility Function

editWells(G, W, rock, varargin)¶

Edit well setup

Synopsis:

% Blocking call
W = editWells(G, W, rock)

Description:

Interactive well editor.

Keyword Arguments:
Parameters:	G – Grid W – Well structure as defined by for exampel addWell. rock – Valid rock structure suitable for input to addWell.
	‘callback’ – Callback function to execute once wells have changed. edit – Allow editing of wells (Note: Editing wells makes it easy to produce ill-defined wells, so use with care. plot – Plot wells during the process. add – Allow adding of wells figure – Figure where wells will be plotted. parent – Parent figure for embedding of the panel. remove – Allow removal of existing wells.
Returns:	W – Updated well structure.

Note

This tool is meant for experienced users who know exactly what they want to change. It at the moment quite easy to produce wells capable of crashing most, if not all, the solvers in MRST.

See also

interactiveSelection

extractSubcellsInteractive(G, varargin)¶

Extract a subset of cells from a grid interactively.

Synopsis:

cells = extractSubcellsInteractive(G)
cells = extractSubcellsInteractive(G, rock.poro)
extractSubcellsInteractive(G)

Description:

Interactive extraction of a subset of cells. First click defines i/j index to show subsets. The second plot can then be clicked to toggle selection. Middle mouse can select entire column.

Keyword Arguments:
Parameters:	G – Valid grid structure.
	data – Plot a dataset onto the grid to make selection easier.
Returns:	Selected subset.

Note

This function is under active development and is subject to change.

Example:

G = cartGrid([10,10,3])
G = computeGeometry(G);
c = extractSubcellsInteractive(G, rand(G.cells.num, 1))

fastRotateButton(varargin)¶

Hook in faster rotation for 3D plots.

Synopsis:

fastRotateButton();

Description:

This function replaces the rotate3d function with a much faster local version specialized for 3d visualization. Used internally by mrst and is subject to change.

Parameters:	None. –
Returns:	Nothing.

Note

fastRotateButton is primarily intended for internal use. It can be used quite generally to speed up rotation, but no guarantees are made with regards to parity with the original rotate3d function.

Example:

G = cartGrid([100, 100, 1]);
plotGrid(G);
fastRotateButton();

See also

altRotate, plotToolbar

getStructFields(G, s, name)¶

Dump possible plotting fields of a struct into human readable format.

Synopsis:

flds = getStructFields(G, rock, 'dataset')

Description:

getStructFields finds all plottable struct fields (typically G.cells.num long vectors) and returns them as a set of possible strings to be passed onto readStructField.

Parameters:	G – Target grid for plotting. s – Struct with fields suitable for plotting, or simply a numerical array.
Returns:	A list of names in the form – ‘rock.poro’, ‘rock.perm:1’, ‘rock.perm:2’ etc.

See also

readStructFields, datasetSelector

logColorbar(varargin)¶

Create colorbar for log dataset

Synopsis:

h = logColorbar();

Note

This function is identical to Matlab builtin colorbar, but with tick labels indicating that the data is log10-transformed.

See also

colorbar

mrstFigure(varargin)¶

Create or select figure with convenient default options for 3d plotting

Synopsis:

h = mrstFigure();
mrstFigure(h);
mrstFigure(h, 'background', 'fast');

Description:

This function is intended to act as figure() when the figure is intended to plot 3D datasets. This allows for easier syntax and ensures that reasonable default parameters can be set. For instance, the default renderer will be set to OpenGL, which will avoid certain crashes when plotting programatically.

Keyword Arguments:

Supply as keywords, i.e. mrstFigure (‘keyword’)
mrstFigure (h, ‘background’) – set current figure to h, without making
the window pop up.
mrstFigure (h, ‘fast’) – set DrawMode to fast for faster drawing, but
somewhat uglier appearance in presence of transparency. Note that this
can prevent some crashes.
mrstFigure (h, ‘matlabrotate’) – Use standard MATLAB rotate function
which may be slower.
mrstFigure (h, ‘painters’) – Use default renderer instead of OpenGL.

Returns:

h – handle to current figure.

Example:

G = cartGrid([10 10 1]);
mrstFigure();
plotGrid(G);

plotCellVectorData(G, data, varargin)¶

Plot a vector field defined per cell

Synopsis:

h = plotCellVectorData(G, vectordata);

% Increase line width, 10 different colors.
h = plotCellVectorData(G, vectordata, 'linewidth', 3, 'n', 10);

Description:

plotCellVectorData plots cell-wise vector fields of the same dimension as the grid. The values are normalized to the size of the grid, giving relatively useful output even on fully unstructured datasets. Current colormap is used to colorize the vectors, but as they do not use CData the vector plot can be combined with e.g. a pressure field plotted by plotCellData.

Keyword Arguments:
Parameters:	G – Valid grid structure data – Dataset of size(G.cells.num, G.griddim) interpreted as a vector field. cells - Vector of cell indices defining sub grid. The graphical output of function ‘plotCellVectorData’ will be restricted to the subset of cells from ‘G’ represented by ‘cells’. If unspecified, function ‘plotCellVectorData’ will behave as if the user defined cells = 1 : G.cells.num meaning graphical output will be produced for all cells in the grid model ‘G’. If ‘cells’ is empty (i.e., if ISEMPTY(cells)), then no graphical output will be produced.
	‘linewidth’ – Width of the underlying quiver plot vectors. Default 2. ‘Scale’ – Adjustment parameter for scaling of the vector arrows. If the default is too small/large, this can be increased/decreased from the default value of 1. ‘Colormap’ – Function handle @(N) which produces the colormap for N entries used to colorize the vector field subset. ‘N’ – The vector data is binned using the number of unique elements, up to a maximum of 64. Increasing this will increase color resolution at the cost of execution speed.
Returns:	h – Handles to up to N different quiverplots.

Example:

cellFlux = faceFlux2cellVelocity(G, state.flux);
plotCellVectorData(G, cellFlux);

See also

plotCellData, plotToolbar, quiver3, quiver

plotCurveTube(curve, radius, varargin)¶

Plot a curve as a tube with variable width

Synopsis:

plotCurveTube(points, radius)
plotCurveTube(points, radius, 'data', data)

Description:

Plot a curve given by consecutive points as a variable radius tube, with optional colorization based on some underlying dataset. Typical usage is for plotting of well trajectories.

Keyword Arguments:
Parameters:	curve – N by 3 array where each row corresponds to the 3D coordinates of points along the curve. radius – Either one value per point in “curve”, or a single point to be used for all points. The radius determines the radius of the tube plotted.
	data – Dataset with one value per curve point given as a column vector. Will be used to colorize the tube based on the current figure colormap. interpMethod – Type of interpolation used when refining the curve. Uses standard Matlab interp1 options. Default: Linear. interpDataMethod – Type of interpolation used to interpolate data between points. Default: Linear. EdgeColor – Edge color for final patch object. Refine – Refinement factor for curve. Default to 1, which is no refinement. Larger values will give a smoother curve when using e.g. spline interpolation.
Returns:	Nothing.

Example:

pts = [0, 0, 5; 0 0 -1; .25 .25 -5; .25, .25, -10];
plotCurveTube(pts, 0.1, 'data', pts(:, 3), 'interpMethod', 'spline',...
             'refine', 10)

See also

getStructFields, datasetSelector

setRenderFixes(varargin)¶

Set fixes which may reduce crashes in MATLAB plots.

Synopsis:

setRenderFixes()
setRenderFixes(gcf)
setRenderFixes(true)
setRenderFixes(gcf, false)

Description:

This utility sets two figure and axes properties to values which are known to remove some crashes and oddball behavior with MATLAB plots. If you are not experiencing problems, this file should NOT be used.

The problems it attempts to fix are:

Issued with multi monitor setups when figures become

unresponsive accompanied by a stack trace with references to jwt errors. The fix is to set default renderer to opengl, which enables plots to appear on any screen without strange behavior. It should be noted that OpenGL plots have several limitations, for instance missing support for logarithmic axes.

Hard crash in MATLAB when plotting more complex figures

involving transparent patches, such as large reservoir cases. The solution is to set drawmode to fast on the axes, but this can have strange side effects when rotating objects later on.

Fixes can be applied and removed, either globally or per figure basis. See next section.

Keyword Arguments:
	h – Handle to figure fixes should be applied to. Defaults to 0 (root figure, defaults are applied system wide (!!!) ). status – Boolean. If true, fixes are applied (Default). If false, fixes are removed.
Returns:	Nothing. Changes state of one or more figures.

visualizeEclipseOutput(prefix)¶: Simple, experimental Eclipse output visualization function. Intentionally undocumented.

mrst-gui: Graphical user-interfaces for MRST¶

`mrst-gui`: Graphical user-interfaces for MRST¶