API Reference

iview(x; kwargs...)

Front-door dispatcher over the Qt + VTK viewers. x may be:

• a GMTgrid -> view_grid
• a GMTimage -> view_image (bare image: flat plane, top-down map)
• a GMTfv -> view_fv (faceted z-colour + matching colorbar; color=:explicit for baked colours)
• a GMTdataset / Vector{GMTdataset} -> points -> view_points; polygons -> view_fv(poly2fv(...))
• a String -> "grid"/"peaks" demo or a grid file -> view_grid; else a named solid from SOLIDS -> view_fv

With no argument, iview() opens an empty drag-and-drop launcher window: drop a grid / image / table file (anything GMT.gmtread reads) onto it — or onto any open viewer window — to open it in a new window.

E.g. iview("torus"), iview(GMT.peaks()), iview(poly_dataset), iview(torus(R=6)), iview(). Line geometry has no standalone window here — overlay it on a grid with add! instead.

iview() -> QtEmpty

Open an empty viewer window that acts as a drag-and-drop launcher: drop a grid, image, or table file (anything GMT.gmtread understands) onto it — or onto any open viewer window — and it is added to that window and listed in its "Scene Objects" panel. Returns a QtEmpty handle.

view_grid(G::GMTgrid; cmap=:auto, drape=nothing, outside=:shademesh, outside_color=200,
		  title="i'GMT", geographic=nothing)

Show a GMT.jl grid in the Qt + VTK viewer. Returns a QtFigure handle immediately; the window stays live while you keep using the REPL. Pass the handle to add! to add elements (lines/points) to this window later. cmap is any GMT colormap name (e.g. :geo, :turbo, :rainbow, :roma), applied LINEARLY over the grid's z range via makecpt; pass nothing for the built-in ramp. The default :auto picks :geo for topo/bathymetry grids (those GMT tags with cpt == "geo") and :turbo for everything else. drape is an optional GMTimage textured over the surface instead of the CPT colouring.

outside controls the grid area the drape image does NOT cover (mirrors GMTF3D):

• :shademesh (default) — flat outside_color fill (uncovered reads as the shaded surface).
• :shade — flat outside_color fill.
• :transparent — see-through; the CPT-coloured base surface shows through.

outside_color is a grey 0-255 int or an (r,g,b) tuple (0-255 ints or 0-1 floats).

The surface mesh (wire edges) is HIDDEN by default; press e in the viewer to toggle it on/off (works on both the base surface and any drape).

triangulate (default true) builds the surface from 2 triangles per grid cell (diagonals, GMTF3D-style); pass false for a single quad per cell.

data overlays a GMTdataset (single or multi-segment Vector{GMTdataset}) on the surface, drawn as mode=:lines (default) or mode=:points. Its z comes from column 3 if present, else is sampled off the grid so it drapes on the relief. data_color is a grey 0-255 int, an (r,g,b) (0-255 ints or 0-1 floats), or nothing (black lines / red points). data_size sets the line width or point size in px (0 = default). Right-click an overlay for a context menu to change its colour, line style/width (lines) or size and round/square (points).

vcurtain hangs a Fledermaus-style vertical image curtain (seismic / midwater profile) along an XY track through the scene — one spec NamedTuple, or a vector of them: (; image, path, zrange, spacing=:distance, flipv=false, clip=false, clip_n=300) (same fields as add_curtain!). E.g. view_grid(G; vcurtain=(; image="sect.jpg", path=track, zrange=(-10000,0), clip=true)).

geographic is auto-detected (override with true/false). For geographic grids the vertical exaggeration is referenced to metres (1°lat ≈ 111111 m, 1°lon = that × cos(mid-lat)); z assumed metres.

view_image(I::GMTimage; title="i'GMT", geographic=nothing, axes=nothing)

Show a bare GMTimage (no elevation) in the viewer: a flat plane textured with the image, opened maximized in a top-down orthographic map. Returns a QtImage handle immediately (the window stays live while you use the REPL). The status-bar readout shows the pixel colour (rgb = R G B) under the cursor instead of a z value. geographic is auto-detected (GMT.isgeog); override with true/false. Also reachable as iview(I).

add!(fig::QtFigure, data; mode=:lines, color=nothing, size=0)

Add elements to an existing viewer window fig (returned by view_grid). data is a GMTdataset (single or multi-segment Vector{GMTdataset}), or an N×2/N×3 matrix, drawn as mode=:lines (default) or mode=:points. Elements with no z column are draped on the figure's surface. color is a name (:red, :black, ...), a 0-255 grey, an (r,g,b) (0-255 ints or 0-1 floats), or nothing (black lines / red points). size is the line width or point size in px (0 = default). Returns fig.

(Named add!, not plot!, to avoid clashing with GMT.jl's plot!.)

add!(p::QtXYPlot, x, y; name="", color=nothing, linewidth=0) -> QtXYPlot

Add another (x, y) line to an open X,Y plot window. Same keyword semantics as xyplot.

add_curtain!(fig::QtFigure, path; image, zrange, spacing=:distance, flipv=false,
			 clip=false, clip_n=300)

Hang a Fledermaus-style vertical image curtain on the wall that follows the XY path through fig's scene (a seismic / midwater profile). Returns fig.

• path — an N×2 matrix (or GMTdataset) of the track in the grid's XY coords (N=2 = a straight two-point curtain; more points weave).
• image — a GMTimage (in-memory) OR a file-path String (gmtread).
• zrange=(zmin,zmax) — the curtain's vertical extent in TRUE z units (same as the grid).
• spacing — :distance (image stretched by chord length, default) or :simple (even per point).
• flipv — invert the image's vertical sense (default first scanline → top).
• clip — cut the curtain's top edge to the grid surface so the wall hugs the relief (the image above the seafloor is dropped). Densifies the track to clip_n columns and samples fig.G along it.

The curtain shares the surface's vertical scale, so it rises/falls with the relief when the vertical exaggeration changes, and it appears in the Scene Objects panel (hideable).

view_points(D; cmap=:turbo, pointsize=4, pickcolor=(0.83,0.83,0.83),
			geographic=nothing, title=...)

Show a point cloud — a GMTdataset or an N×≥3 matrix of x y z [...] rows — in the Qt + VTK viewer, colouring each point by its z through the GMT colormap cmap (any GMT name, e.g. :turbo, :roma, :geo; nothing = the built-in ramp). Returns a QtPoints handle immediately; the window stays live while you keep using the REPL.

Ctrl+right-drag a box over the cloud to select points (TOGGLE — re-dragging the same box deselects; Ctrl+Z undoes the last change). Plain right-drag stays the dolly. The selected points are highlighted in pickcolor and kept for you — read them back with selection, which returns a copy of the picked x y z [...] rows (or nothing).

• pointsize — point size in px.
• pickcolor — highlight colour for selected points: an (r,g,b) (0-255 ints or 0-1 floats) or a grey number.
• geographic — auto-detected for a GMTdataset (override with true/false); treats x,y as degrees and z as metres for a physically-true vertical scale.

selection(fig::QtPoints) -> Matrix

Return a copy of the point-cloud rows currently selected with Ctrl+right-drag in the viewer (x y z [...]), or an EMPTY matrix (0 rows, same columns) if none are selected (or the window is closed). Test with isempty.

view_fv(name::AbstractString; color=true, cmap=:turbo, edges=false, geographic=nothing,
		title="", solid_kwargs...)

Show a NAMED GMT solid from the SOLIDS catalogue ("cube", "sphere", "torus", "icosahedron", "octahedron", "dodecahedron", "tetrahedron", "cylinder", "revolve", "loft", "extrude"). The solid takes its OWN parameters — any kwarg that is NOT a viewer keyword is forwarded untouched to the GMT generator:

view_fv("cube"; r=3)                 # r = circumradius (centre→vertex)
view_fv("sphere"; n=4)               # sphere's own subdivision level
view_fv("torus"; R=8, nx=200, edges=true)
view_fv("revolve"; curve=mycurve)    # your own profile (else a demo profile)

color behaves as in view_fv(::GMTfv): true (default) = FACETED per-face colour by mean z through cmap with a MATCHING colorbar; false = smooth per-vertex z; :explicit = the solid's own baked colours (no colorbar). The remaining viewer kwargs (cmap, edges, geographic, title) behave the same.

poly2fv(D::Vector{<:GMTdataset}; cmap=:turbo, zscale=:auto, vfrac=0.2, vexag=:auto,
		isgeog=false, ncolor=256, triangulate=false) -> GMTfv

Fold a vector of closed 3-D polygons into a single coloured GMTfv ready for view_fv — one mesh face per polygon, any corner count. Each polygon needs x y z columns; a repeated closing vertex is dropped. Faces are coloured by their mean z through the GMT colormap cmap. Pass triangulate=true to fan-split every polygon into triangles (concave / non-planar polys).

xyplot(x, y; name="", color=nothing, linewidth=0, title="", xlabel="X", ylabel="Y") -> QtXYPlot

Open a standalone X,Y plot window and draw the (x, y) series. y may be a matrix whose columns are separate lines sharing the same x. color accepts a name (:red, "blue"), a 0–255 / 0–1 triple, or nothing for the default. xlabel/ylabel set the axis titles. Returns a live QtXYPlot handle; add more lines with add!. Non-blocking.

t = range(0, 4π; length=400) |> collect
p = xyplot(t, sin.(t); name="sin", title="demo", ylabel="amplitude")
add!(p, t, cos.(t); name="cos", color=:blue)

clear!(p::QtXYPlot) -> QtXYPlot

Remove every series from an open X,Y plot window.

xtime!(p::QtXYPlot, mode) -> QtXYPlot

Format the X axis as time, reading X as Unix epoch seconds. mode is :linear (plain numbers), :date (auto by span), :date_ymd (yyyy-mm-dd), :time (HH:MM), :decyear (decimal year) or :doy (decimal day-of-year). Ticks auto-update on zoom/pan.

logscale!(p::QtXYPlot; x=nothing, y=nothing) -> QtXYPlot

Set base-10 log scaling on the X and/or Y axis (true = log, false = linear, nothing = leave unchanged). Data on a log axis must be positive.

stickplot(t, u, v; scale=:auto, color=nothing, title="Stick diagram", kwargs...) -> QtXYPlot
stickplot(t, azimuth; mag=nothing, kwargs...) -> QtXYPlot

Draw a stick (vector) diagram: at each t a vector is plotted from the y=0 baseline. Give the vectors as (u, v) components, or as azimuth degrees (oceanographic: 0° = up/North, clockwise) with optional mag (default 1). scale sizes the sticks (:auto ≈ 5 % of the time span per full-magnitude vector). Returns a QtXYPlot; extra keywords (xlabel, ylabel, xtime, name) pass through.

t  = collect(0:0.5:48)                 # hours
az = 90 .+ 60 .* sin.(2π .* t ./ 12)   # tide-turning current direction
stickplot(t, az; mag=1 .+ 0.3 .* cos.(2π .* t ./ 12), title="Current sticks", xlabel="hour")

movie(frame!::Function, fig::InteractiveGMT figure; frames, kwargs...) -> String
movie(fig, frame!::Function; frames, kwargs...) -> String

Create a movie from a live InteractiveGMT Qt/VTK scene. This method extends GMT.movie by Julia dispatch; the existing GMT.jl script-based movie(main; ...) method is unchanged.

For each normalized frame, frame!(fig, f::MovieFrame) mutates the live scene and InteractiveGMT captures the VTK render surface belonging to that exact figure. PNG frames are encoded directly with FFmpeg for format=:mp4, :webm, or :gif; format=:png leaves the PNG sequence as the product.

frames accepts a positive integer, range/vector, matrix (one row per frame), GMTdataset-like object with a matrix .data, or a text table filename. MovieFrame.frame is zero-based like GMT movie's MOVIE_FRAME; cols, text, and words are the in-process counterparts of MOVIE_COL*, MOVIE_TEXT, and MOVIE_WORD*.

Supported GMT-style keyword aliases in this first backend are T/frames, N/name, D/frame_rate, F/format, W/work_dir, Z/clean, H/scale, and Q/debug. scale is currently VTK capture magnification; GMT's supersample-then-downsample -H semantics are a follow-up refinement.

By default the original display state (camera, VE, 2-D/3-D mode, colorbar placement) is restored after rendering, even on an error. Arbitrary data/overlay mutations performed by the callback are not rolled back.

movie(fig; kwargs...) -> String

Animate the 3-D dataset fig is showing along its layer axis, with no callback to write: the frame mutation is set_layer! and frames defaults to every layer. Works on either kind of layered dataset the viewer has — a plain netCDF cube or an Aquamoto (NSWING tsunami) cube. Every keyword of the callback methods applies.

fig = ...                       # a window with a cube open
movie(fig; name="cube", frame_rate=15, clean=true)

Here frames counts in LAYER NUMBERS, not in offsets: frames=20:80 animates layers 20 through 80, frames=1:2:nlayers(fig) takes every second layer, and a bare frames=n means layers 1:n. Write the callback out when a frame has to do more than change the layer:

movie(fig; frames=nlayers(fig)) do fig, f
    set_layer!(fig, f.index); orbit!(fig, 0.5)
end

orbit!(fig, azimuth, elevation=0; zoom=1) -> fig

Apply a relative VTK camera orbit to one InteractiveGMT window and render it. This is the simplest movie callback primitive; azimuth and elevation are degrees and zoom > 0 is multiplicative.

set_layer!(fig, k) -> fig

Show layer k of the 3-D dataset fig is displaying, 1-based like MovieFrame.index and like both layer sliders in the UI (only the internal calls are 0-based).

Works on either kind of layered dataset the viewer has, through that kind's OWN existing switcher — _on_load_cube_layer for a plain netCDF cube, _aquamoto_slice for an NSWING tsunami cube. Neither is reimplemented here, and each is driven with the display options its own dialog last rendered with: the cube's "global min/max" choice, and the tsunami's Split Dry/Wet, colour scaling, transparency and shading toggles. So an animation looks exactly like the layer on screen — including, for a tsunami, the per-slice water relight the two-surface illumination law requires.

replace_grid!(fig::QtFigure, G::GMTgrid; name="", zrange=nothing) -> fig

Replace the base grid in a live InteractiveGMT scene without rebuilding the window, preserving its camera, vertical exaggeration and overlays. Movie use intentionally requires the new grid to have the same x/y geometry as the current base grid; changing the mesh geometry while animating would invalidate a fixed camera and is outside the first movie backend. Pass zrange=(zmin,zmax) to keep a stable colour scale across frames instead of autoscaling each replacement grid independently.

nlayers(fig) -> Int

Number of layers in the 3-D dataset fig is showing — a plain netCDF cube's third dimension, or an Aquamoto (NSWING tsunami) cube's time steps. Errors when the window has neither. This is the natural frames value for a layer animation:

movie(fig; frames=nlayers(fig), name="cube") do fig, f
    set_layer!(fig, f.index)
end

add_label!(fig; kind=:frame, …) -> Int

Add a movie frame label (GMT movie -L) to a live window and return its id. The label is a real scene element: it gets its own row under "Movie annotations" in Scene Objects, with a checkbox, a properties menu and Remove, and it is visible immediately — you can place it before spending a render on it. movie() fills in its text frame by frame.

kind picks what the label says, matching GMT's -L:

Keywords: text (for :string), column, format (a C-format applied to the value, GMT +t), scale (+s), justify (+j, one of TL TC TR ML MC MR BL BC BR), offset (+o, pixels, a number or a pair), font (a GMT font spec, +f), fontsize/color (the same in pieces), fill (+g), pen/penwidth (+p), clearance (+c), rounded (+r), and name for the Scene Objects row.

A raw GMT spec works too and parses to exactly the same element: add_label!(fig, "f+jTL+gwhite").

add_progress!(fig; style=:a, …) -> Int

Add a movie progress indicator (GMT movie -P) to a live window and return its id. Like add_label! it is a real scene element with its own Scene Objects row, properties and Remove.

style selects one of GMT's six indicators; a–c are circular, d–f are axis-like:

All of them grow clockwise from 12 o'clock (circular) or left to right (linear). Circular indicators default to justify=:TR at 5 % of the larger window dimension; linear ones to justify=:BC at 60 % of the window width — pass justify and width (pixels, GMT +w) to override.

Set annot=true (GMT +a) to give the indicator a label of its own, driven by the same kind / column / format / scale keywords add_label! takes. Style a has no label in GMT and gets none here. moving/static set the two colours (+g/+G or +p/+P), movingwidth/staticwidth their pen widths.

A raw GMT spec works too: add_progress!(fig, "b+w200+jBL").

remove_annotation!(fig, id) -> Bool

Remove one movie label or progress indicator by the id its constructor returned. Removing it from Scene Objects (its row's Remove) does the same thing; both go through the viewer's own remove, so the host registry cannot outlive the element.

movie_annotations(fig) -> Vector{Int}

The ids of the movie labels and progress indicators this window carries, oldest first.

True while the figure's window is still open (closing it invalidates the handle).

save_png(path) -> Bool

Save a PNG of the most-recently-opened viewer window to path. Returns true on success.

save_png(fig, path; scale=1) -> Bool

Save the VTK render surface belonging to fig to path. Unlike save_png(path), this variant is figure-specific and therefore safe when several InteractiveGMT windows are open. scale is an integer VTK capture magnification (1 keeps the window's current pixel size).

wait_windows()

Block (yielding, so the Qt pump keeps running) until every viewer window is closed. Useful at the tail of a julia script.jl run, where there is no REPL to keep the process alive.

stereo!(fig, on=-1) -> Bool

Toggle red/cyan anaglyph stereo on a viewer window (use cheap red/cyan 3-D glasses to see real depth on the relief). on=true enables, on=false disables, default -1 flips the current state. Sets the stereo type to anaglyph so it actually renders on a normal monitor. Returns the new state (true = on). fig is any viewer handle (QtFigure/QtPoints/QtFV).

show_table(fig, data; name="")

Show data in the window's Data Viewer spreadsheet tab and bring that tab forward. fig is any viewer handle (QtFigure/QtPoints/QtFV); data is a GMTdataset (single or multi-segment Vector{GMTdataset}), a plain matrix, or a vector. name labels the tab (defaults to the dataset's header / "matrix" / "vector"). Returns fig.

The empty (unreferenced) CRS.

CRS(proj4, wkt, epsg)

A coordinate reference system in its three interchangeable forms. An empty proj4 and wkt with epsg == 0 means UNREFERENCED data. Build one from a GMT object with crs_from.

What one file (or one of its sub-datasets) turned out to be. The Julia stand-in for Mirone's att.

The L2 reinterpolation settings, from L2config.txt and/or the keywords.

Options gathered from the list-file header (-A -B -R -G -D -F) and from the keywords.

One normalized frame presented to an InteractiveGMT movie callback.

One spacecraft/sensor row of the Instrument combo.

• dir — the showimages/<DIR> path element
• prefix — the file-name prefix (AQUA_MODIS.2026…)
• first — first day the mission has L3 data for; the browser must never look further back
• yr_first/yr_last — the years for which ANNUAL (YR) composites exist. yr_last == 0 marks a mission with no annual products at all (NOAA-20), so the Period combo can grey "Annual" out.
• products — indices into _OC_PRODUCTS this mission actually flies. Not every sensor carries every product: the OLCI pair is an ocean-colour imager with no thermal bands, so it has chlorophyll and no SST at all. The dialog greys the rest out rather than offering a search that can only come back empty.

One row of the Product combo: an OB.DAAC suite (the NSST in the file name) plus the variable it stores (sst) and the grid resolution to ask for.

One parsed line/point overlay out of gmtvtk_serialize_overlays' blob.

One parsed ruler measurement out of gmtvtk_serialize_rulers' blob (its clicked vertices).

One parsed symbol layer out of gmtvtk_serialize_symbols' blob. xyz holds the points AS STORED — x is still multiplied by xfac (addSymbols bakes it in); _symbol_layer un-bakes it for GMT, and the session rebuild hands them back to a C side that bakes it again, so neither may do it here. scale / rgb are empty when the layer has no per-point size / colour.

One parsed label out of the text serializer's blob.

movie(frame!::Function, fig::InteractiveGMT figure; frames, kwargs...) -> String
movie(fig, frame!::Function; frames, kwargs...) -> String

Create a movie from a live InteractiveGMT Qt/VTK scene. This method extends GMT.movie by Julia dispatch; the existing GMT.jl script-based movie(main; ...) method is unchanged.

For each normalized frame, frame!(fig, f::MovieFrame) mutates the live scene and InteractiveGMT captures the VTK render surface belonging to that exact figure. PNG frames are encoded directly with FFmpeg for format=:mp4, :webm, or :gif; format=:png leaves the PNG sequence as the product.

frames accepts a positive integer, range/vector, matrix (one row per frame), GMTdataset-like object with a matrix .data, or a text table filename. MovieFrame.frame is zero-based like GMT movie's MOVIE_FRAME; cols, text, and words are the in-process counterparts of MOVIE_COL*, MOVIE_TEXT, and MOVIE_WORD*.

Supported GMT-style keyword aliases in this first backend are T/frames, N/name, D/frame_rate, F/format, W/work_dir, Z/clean, H/scale, and Q/debug. scale is currently VTK capture magnification; GMT's supersample-then-downsample -H semantics are a follow-up refinement.

By default the original display state (camera, VE, 2-D/3-D mode, colorbar placement) is restored after rendering, even on an error. Arbitrary data/overlay mutations performed by the callback are not rolled back.

movie(fig; kwargs...) -> String

Animate the 3-D dataset fig is showing along its layer axis, with no callback to write: the frame mutation is set_layer! and frames defaults to every layer. Works on either kind of layered dataset the viewer has — a plain netCDF cube or an Aquamoto (NSWING tsunami) cube. Every keyword of the callback methods applies.

fig = ...                       # a window with a cube open
movie(fig; name="cube", frame_rate=15, clean=true)

Here frames counts in LAYER NUMBERS, not in offsets: frames=20:80 animates layers 20 through 80, frames=1:2:nlayers(fig) takes every second layer, and a bare frames=n means layers 1:n. Write the callback out when a frame has to do more than change the layer:

movie(fig; frames=nlayers(fig)) do fig, f
    set_layer!(fig, f.index); orbit!(fig, 0.5)
end

add!(fig::QtFigure, data; mode=:lines, color=nothing, size=0)

Add elements to an existing viewer window fig (returned by view_grid). data is a GMTdataset (single or multi-segment Vector{GMTdataset}), or an N×2/N×3 matrix, drawn as mode=:lines (default) or mode=:points. Elements with no z column are draped on the figure's surface. color is a name (:red, :black, ...), a 0-255 grey, an (r,g,b) (0-255 ints or 0-1 floats), or nothing (black lines / red points). size is the line width or point size in px (0 = default). Returns fig.

(Named add!, not plot!, to avoid clashing with GMT.jl's plot!.)

add!(p::QtXYPlot, x, y; name="", color=nothing, linewidth=0) -> QtXYPlot

Add another (x, y) line to an open X,Y plot window. Same keyword semantics as xyplot.

add_curtain!(fig::QtFigure, path; image, zrange, spacing=:distance, flipv=false,
			 clip=false, clip_n=300)

Hang a Fledermaus-style vertical image curtain on the wall that follows the XY path through fig's scene (a seismic / midwater profile). Returns fig.

• path — an N×2 matrix (or GMTdataset) of the track in the grid's XY coords (N=2 = a straight two-point curtain; more points weave).
• image — a GMTimage (in-memory) OR a file-path String (gmtread).
• zrange=(zmin,zmax) — the curtain's vertical extent in TRUE z units (same as the grid).
• spacing — :distance (image stretched by chord length, default) or :simple (even per point).
• flipv — invert the image's vertical sense (default first scanline → top).
• clip — cut the curtain's top edge to the grid surface so the wall hugs the relief (the image above the seafloor is dropped). Densifies the track to clip_n columns and samples fig.G along it.

The curtain shares the surface's vertical scale, so it rises/falls with the relief when the vertical exaggeration changes, and it appears in the Scene Objects panel (hideable).

add_label!(fig; kind=:frame, …) -> Int

Add a movie frame label (GMT movie -L) to a live window and return its id. The label is a real scene element: it gets its own row under "Movie annotations" in Scene Objects, with a checkbox, a properties menu and Remove, and it is visible immediately — you can place it before spending a render on it. movie() fills in its text frame by frame.

kind picks what the label says, matching GMT's -L:

Keywords: text (for :string), column, format (a C-format applied to the value, GMT +t), scale (+s), justify (+j, one of TL TC TR ML MC MR BL BC BR), offset (+o, pixels, a number or a pair), font (a GMT font spec, +f), fontsize/color (the same in pieces), fill (+g), pen/penwidth (+p), clearance (+c), rounded (+r), and name for the Scene Objects row.

A raw GMT spec works too and parses to exactly the same element: add_label!(fig, "f+jTL+gwhite").

add_progress!(fig; style=:a, …) -> Int

Add a movie progress indicator (GMT movie -P) to a live window and return its id. Like add_label! it is a real scene element with its own Scene Objects row, properties and Remove.

style selects one of GMT's six indicators; a–c are circular, d–f are axis-like:

All of them grow clockwise from 12 o'clock (circular) or left to right (linear). Circular indicators default to justify=:TR at 5 % of the larger window dimension; linear ones to justify=:BC at 60 % of the window width — pass justify and width (pixels, GMT +w) to override.

Set annot=true (GMT +a) to give the indicator a label of its own, driven by the same kind / column / format / scale keywords add_label! takes. Style a has no label in GMT and gets none here. moving/static set the two colours (+g/+G or +p/+P), movingwidth/staticwidth their pen widths.

A raw GMT spec works too: add_progress!(fig, "b+w200+jBL").

add_symbols!(handle, x, y; z=0, symbol=:c, size=8, sizeunit=:px,
             fill=:yellow, edge=:black, edgewidth=1.0, filled=true)

Stamp a screen-constant symbol layer at points (x, y[, z]) (TRUE data coords) on an existing viewer handle (a QtFigure or a raw Scene* Ptr). symbol is a friendly name (:circle, :square, :triangle, :itriangle, :diamond, :hexagon, :pentagon, :octagon, :star, :cross, :plus, :dash, :sphere, :cube) or a 1-char GMT code. :sphere/:cube are true 3-D, lit volumes (visible from any angle, e.g. edge-on in perspective) — every other shape is a flat, unlit XY glyph. size is on screen, in :px or :pt. fill and edge accept any colour _ovl_color understands (name Symbol/String, 0-1 or 0-255 tuple). Symbols stay the same pixel size at any zoom. Returns true if the layer was added.

clear!(p::QtXYPlot) -> QtXYPlot

Remove every series from an open X,Y plot window.

clipMySpikes!(Z::Matrix{<:AbstractFloat}) -> Z

MODIS L2 SST carries a strong noise that peaks every other 10 rows in sensor coordinates. Replacing the spiky value by the average of its two neighbours reduces (does not eliminate) the effect.

crs_from(O; geographic=false) -> CRS

Build the CRS for a GMT object (GMTgrid, GMTimage, GMTdataset, GMTfv, …): read whatever PROJ4 / WKT / EPSG it carries, then derive the missing forms with GMT.jl's converters, using PROJ4 as the pivot. geographic=true resolves a plain lon/lat object with no explicit projection to WGS84 (EPSG 4326). Returns NO_CRS for unreferenced data.

f, f1, f2 = csaps_nodes(x, V, p)

Fit the cubic smoothing spline of csaps(x, V(:,k), p) to every COLUMN of V (size(V,1) == length(x)) and return its value, first derivative and second derivative AT THE DATA SITES — the three things fnval(fnder(pp,k), x) gives in the .m, without ever materialising a pp-form.

From csaps1's pp coefficients on interval j (local variable t = x - x[j]): f = c1·t³ + 3·c3[j]·t² + c2[j]·t + y[j], so at t = 0 the value is y[j] (the smoothed data), f' = c2[j] and f'' = 6·c3[j]; the last node is evaluated at t = dx[n-1] of interval n-1.

p = csaps_p_guess(x)

csaps's own estimate of the smoothing parameter for data sites x: 1/(1 + trace(R)/(6·trace(Q'Q))) (splfun.m csaps1, the p < 0 branch). It behaves like `1/(1 + xunit^3/lambda_unit)`, so it is a pure function of the node spacing — which is why Mirone reads it off a 5-node corner of the grid.

empilhador(listfile::String; kwargs...)
empilhador(fnames::Vector{String}; kwargs...)

Stack a collection of 2-D grids (or MODIS/VIIRS/SeaWiFS L2 scenes) into a single 3-D file.

Arguments

• listfile: A text file with the list of file names (1, 2 or 3 columns, see below). It may also be a wildcard request of the form "C:/a1/*.L2_LAC_SST4 ? -sst4", in which case the list file is built on the fly next to the data.
• fnames: Alternatively, the vector of file names itself.

Keywords

• outfile | save: Name of the output file. When not given (and no -G in the list file header) the stack is returned in memory as a GMTgrid cube (:netcdf/:tiff only).
• format: :netcdf (default), :tiff (multi-band GeoTIFF), :vtk, or :vrt (a multi-band VRT built with gdalbuildvrt -resolution lowest -separate).
• region: Sub-region as (west, east, south, north).
• sds: Sub-dataset selector, either the number (3 or "sds3") or the name ("-sst4", "sst4").
• quality: SST quality level in [-2 2] (OceanColor qual_sst). Values > quality are dropped; a NEGATIVE value instead turns the array into the 0/1 mask of pixels with qual >= -quality.
• bitflags: true to mask with l2_flags instead of qual_sst, or a comma-separated list of flag names to use in place of the default one. Keys: ATMFAIL, ATMWARN, CHLFAIL, CHLWARN, CLDICE, COCCOLITH, FILTER, HIGLINT, HILT, HISATZEN, HISOLZEN, LAND, LOWLW, MAXAERITER, NAVFAIL, NAVWARN, SSTFAIL, SSTWARN, STRAYLIGHT.
• l2: true to run the "L2 magic" (sensor -> geographic reinterpolation). Implied by inc.
• config: Path of an L2config.txt to read the -R/-I/-C/-N/-S and flag keys from. true means the default ~/.gmt/L2config.txt (created with sane defaults if missing).
• inc: Cell size of the L2 reinterpolation (L2config's -I).
• ncells: surface's mask radius in cells (L2config's -C), i.e. only nodes within ncells cells of a datum survive. 0 disables it.
• nearneighbor: true to grid the L2 scene with nearneighbor instead of surface. Can also be the (-N, -S) pair, e.g. ("2", "0.04").
• despike: true to run clipMySpikes! on the MODIS L2 SST every-other-10-rows noise.
• description: Goes into the netCDF global attribute description.
• append: true to append the new layers to an existing outfile.
• time_from_name, year_in_name: see the ?, ?+ and ?Y list-file markers below.
• zdim_name, z_unit: name and units of the 3rd (vertical/time) dimension, default "time" and none. They land on the cube's v_unit and on the netCDF <dim>#units attribute.
• progress: A f(k, n, name) callback, called before each file is read. The GUI uses it to walk its list box; the default prints nothing.

List file format

Column 1 is the file name (absolute, relative, or bare if it sits next to the list file). Column 2 is the "time" of the layer, or one of:

• ? extract it from the file name (YYYYDDDHHMMSS, YYYYMMDDHHMMSS-..., or TERRA_MODIS.20181223T234501.L2.SST.nc),
• ?+ carry the time that lives inside the file,
• ?Y compose a decimal year from a year in the name (A2016_SST...) plus the internal times,
• * just use the running number.

Column 3, when present, is the sub-dataset: sdsN (number) or -name (name).

A single header line starting with # may carry -A, -B<n>, -R<w/e/s/n>, -G<outfile>, -D<description> (or -D"more than one word") and -F<flagSDS>_<minQuality>. Lines >include <path> splice another list file in. Lines starting with @ are Mirone's "change the CD now" markers and are skipped with a warning (there are no removable media prompts here).

Returns

The output file name when one was written, or a GMTgrid cube when it was not.

Example

empilhador("list.txt", outfile="stack.nc", region=(-25,0,20,45))

gmtedit([file]; width=200.0, center=nothing)

Open the MGD77 track editor — a port of Mirone's gmtedit. Three stacked panels plot a cruise's gravity, magnetics and bathymetry (or whatever three variables the [gmtedit] V= line of ~/.gmt/iGMT.ini names) against along-track distance in km.

Click a point to flag it bad (green → red), click it again to unflag it; drag a rectangle to flag many at once. Shift-click relocates an isolated spike onto the value a cubic spline through its neighbours predicts. The toolbar adds an automatic outlier detector (cubic smoothing spline residuals), a speed/gradient nav filter, and cruise info. Saving writes the surviving values back into the MGD77+ netCDF file, flagged points becoming that variable's missing_value.

file is an MGD77+ netCDF cruise (.nc) or a legacy pre-MGD77 *.gmt binary; with no argument the window opens empty and the file is picked from its toolbar. width is the displayed window width in km (gmtedit's -L); center is a (lon, lat) the display should start centred on (gmtedit's -P). parent is a 3-D viewer handle (a QtFigure, or the window this cruise track is plotted in): it enables the toolbar's link tool, which sends the record you click to that window as a marker at its own lon/lat — gmtedit.m's hMirAxes / ptcoords. Non-blocking — returns the opaque window handle.

Saving writes back in the format the cruise came from. "Save as old *.gmt" always writes the legacy binary, converting an MGD77+ cruise on the way (gmtedit.m's force_gmt).

gmtedit("C:/data/mgd77/01010003.nc")
gmtedit("so_lucky.gmt"; width=300.0, center=(-70.0, 31.0))

fig = iview("C:/data/mgd77/01010003.nc")      # the cruise track, plotted
gmtedit("C:/data/mgd77/01010003.nc"; parent=fig)

gmtreplay(fig; figsize=15, recompute=false) -> the GMT figure

Reproduce the window's display as GMT.jl calls, executed right now against the LIVE grid/image objects — no files are written anywhere. Returns the last call's result and shows the figure.

gmtscript(fig; path="", figsize=15, recompute=false) -> String

Reproduce the window's display as a standalone GMT.jl script and return its text. With path, the script is written there and any in-memory layer is materialized once into a script_data/ directory beside it; without path, nothing is written (layers that would need a sidecar still render their gmtread line, so the text alone shows what the script would be).

recompute=true emits the recorded GMT command for a computed grid instead of its data, which makes the script editable — see docs/GMTSCRIPT_PLAN.md, tier T1. It is skipped, with a note, for any grid whose command references files that no longer exist.

backdrop=true is the escape hatch: one capture of the whole window under a real frame, for a display made of things GMT cannot draw. The script says plainly that it is a picture.

True if this CRS carries any referencing at all.

True while the figure's window is still open (closing it invalidates the handle).

isoc2shapenc(fname_in::String, fname_out::String; append::Bool=false) -> String

Read a Mirone isochron .dat file (fname_in, data/isocs/*.dat layout) and write it into a SHAPENC netCDF file (fname_out) as a 2-D polyline ensemble, via shapenc. The parsed isochron name becomes the ensemble's name tag attribute, and each parsed pole (FIN, STG0, STG...) becomes its own numeric double[] tag attribute. Pass append=true to add this isochron to an existing SHAPENC file instead of overwriting it (grouping several isochrons in one file).

Example

isoc2shapenc(raw"C:\SVN\mironeWC\data\isocs\c5c_EU_NA.dat", "c5c_EU_NA.nc")

# Group several isochrons of the same plate pair into one file:
isoc2shapenc(raw"C:\SVN\mironeWC\data\isocs\c13_EU_NA.dat", "EU_NA.nc")
isoc2shapenc(raw"C:\SVN\mironeWC\data\isocs\c20_EU_NA.dat", "EU_NA.nc"; append=true)

isoc2shapenc(; isoc_group::Vector{String}=["", "", ""]) -> String

Batch form: group every isochron .dat file belonging to the same plate pair, in one directory, into ONE SHAPENC file — one ensemble per file.

isoc_group = [dir, pattern, savedir] (savedir optional):

• dir — directory to search for .dat files.
• pattern — a plate-pair code "AA_BB" (e.g. "EU_NA"). A file matches when its name ends in _AA_BB.dat OR _BB_AA.dat — either plate order — so "EU_NA" also picks up a ..._NA_EU.dat file, no separate call needed.
• savedir — directory the grouped file is written into; "" (the default, and what an isoc_group with only 2 elements gets) means the current directory.

Each matching file's own name – the WHOLE stem, verbatim, exactly as it appears on disk minus the .dat extension (c5c_EU_NA.dat -> "c5c_EU_NA", c13_NA_EU.dat -> "c13_NA_EU") – becomes that ensemble's ACTUAL netCDF variable name (shapenc's ids, e.g. lonc5c_EU_NA/ latc5c_EU_NA — no Point_/Polygon_/PolyLine_ type prefix either), not just an attribute — a real identifier a future tool can look up (or ncdump -h/GDAL can show) directly as a variable, and NEVER shortened/reconstructed: both plate-order files for one isochron number normally exist (c13_EU_NA.dat AND c13_NA_EU.dat) and are NOT duplicates — they're two DIFFERENT reconstructed geometries, one per plate's reference frame — so the file's own full name is what unambiguously says which one a given ensemble is. Also written as the container-variable name tag attribute for convenience; the fuller descriptive name parsed from the file's own header line (_isoc_parse_header) is kept too, under full_name.

A file whose id (the stem with the plate-pair suffix stripped) is longer than 4 characters is NOT a real isochron (e.g. dist_age_EU_NA.dat -> "dist_age", polos_para_idades_EU_NA.dat -> "polos_para_idades" — unrelated tables that happen to share the plate-pair filename suffix) and is SKIPPED with a warning, not written in.

The output file name is "isochrons_" * pattern * ".nc" — always .nc (input isochron files are the ones that are normally .dat), so it also auto-recognizes as vector data on drag-drop/ File>Open (_shnc_is_shapenc, drop.jl) like any other SHAPENC file.

Re-running this on the same directory/pattern REBUILDS the output file from the CURRENT matching file set (any stale copy is removed first) rather than piling more ensembles onto whatever was already there. All matching files are written in ONE shapenc(...; ids=..., tags=...) call (one ensemble per file), not a loop of one shapenc call per file – a per-file loop reopens the netCDF file from scratch on every call, which is both slower and, worse, forces a fresh per-file coordinate-pair dimension (proven live: at 1368-ensemble scale a per-call reopen loop was measurably worse on both file size and write time than one batched call). The result is still an ordinary SHAPENC/netCDF4 file, further appendable later; this call just doesn't try to guess which of a re-run's ensembles should survive.

Example

isoc2shapenc(; isoc_group=["C:/SVN/mironeWC/data/isocs", "EU_NA"])
# -> "isochrons_EU_NA.nc" in the current directory, picking up both "..._EU_NA.dat" and
# "..._NA_EU.dat" files, one ensemble per file.

iview(x; kwargs...)

Front-door dispatcher over the Qt + VTK viewers. x may be:

• a GMTgrid -> view_grid
• a GMTimage -> view_image (bare image: flat plane, top-down map)
• a GMTfv -> view_fv (faceted z-colour + matching colorbar; color=:explicit for baked colours)
• a GMTdataset / Vector{GMTdataset} -> points -> view_points; polygons -> view_fv(poly2fv(...))
• a String -> "grid"/"peaks" demo or a grid file -> view_grid; else a named solid from SOLIDS -> view_fv

With no argument, iview() opens an empty drag-and-drop launcher window: drop a grid / image / table file (anything GMT.gmtread reads) onto it — or onto any open viewer window — to open it in a new window.

E.g. iview("torus"), iview(GMT.peaks()), iview(poly_dataset), iview(torus(R=6)), iview(). Line geometry has no standalone window here — overlay it on a grid with add! instead.

iview() -> QtEmpty

Open an empty viewer window that acts as a drag-and-drop launcher: drop a grid, image, or table file (anything GMT.gmtread understands) onto it — or onto any open viewer window — and it is added to that window and listed in its "Scene Objects" panel. Returns a QtEmpty handle.

l2config_file(create::Bool=false) -> String

Path of the L2config.txt that drives the "L2 magic": ~/.gmt/L2config.txt, the same home as the other GMT.jl/iGMT settings (Mirone kept it in <mirone>/data/). With create=true a default one is written when it does not exist yet, so the file is always there to be edited.

logscale!(p::QtXYPlot; x=nothing, y=nothing) -> QtXYPlot

Set base-10 log scaling on the X and/or Y axis (true = log, false = linear, nothing = leave unchanged). Data on a log axis must be positive.

mbgrid(data; region, inc, kwargs...) -> GMTgrid

Grid scattered x, y, z with MB-System's MBGRID algorithm: a Gaussian-weighted mean into the grid cells, then a spline through the cells that stayed empty.

data may be a GMTdataset, a vector of them, an N×3 matrix, or three vectors passed positionally as mbgrid(x, y, z; ...).

Required

• region: (w, e, s, n), a 4-vector, or a "w/e/s/n" string.
• inc: one number, (dx, dy), or "dx/dy".

Options

• scale = 1.0 width of the Gaussian, in grid cells (gmtmbgrid's -W). Larger = smoother bins.
• tension = 0.0 spline tension, 0 = minimum curvature (-T). Only used by solver = :zgrid.
• extend = 0.0 widen the working grid by this fraction of nx/ny so data just outside region still constrain the edge, then crop back (-E).
• clipmode :all (default, fill everything the spline reached), :near (only within clip cells of data), :gap (only gaps with data on opposite sides), :none (bin only, leave the gaps NaN). This is -C.
• clip = 0 the radius in cells that :near and :gap use.
• breakline a GMTdataset, vector of them, an N×3 matrix, or a file path. Nodes the line crosses are pinned to its z, undiluted by nearby soundings — a soft breakline.
• registration :gridline (default) or :pixel, as everywhere else in GMT.
• solver :zgrid (default) the IGPP/SIO thin-plate spline, in C, fast, the one MBGRID itself uses; or :surface, which hands the binned nodes to GMT.surface and merges its answer back. :surface is slower but is GMT's own solver, tension and all; :zgrid extrapolates large empty areas more freely, so it can invent dramatic relief far from any data (use :near or :gap to bound it).
• verbose = false spline iteration progress on stderr.

Every option also accepts the string form the Interpolate dialog sends ("1.5", "near").

Returns a GMTgrid with NaN at every node nothing reached.

Example

D = gmtread("soundings.xyz")
G = mbgrid(D; region = (-9.5, -8.5, 36.5, 37.5), inc = 0.002, scale = 1.5, clipmode = :near, clip = 5)
view_grid(G)

R = mirblock(G::GMTgrid; method=0, win=3, geog=nothing)

Moving-window terrain analysis of grid G — Grid Tools > Terrain Modeling, the port of Mirone's mirblock MEX. method is the same number the MEX's -A takes and the same order the dialog lists (see InteractiveGMT.MIRBLOCK_METHODS); win is the (odd) neighbourhood width. geog tells Slope/Aspect whether x,y are degrees and must be converted to metres; nothing reads it off the grid.

Returns a new GMTgrid with G's geometry.

movie_annotations(fig) -> Vector{Int}

The ids of the movie labels and progress indicators this window carries, oldest first.

nlayers(fig) -> Int

Number of layers in the 3-D dataset fig is showing — a plain netCDF cube's third dimension, or an Aquamoto (NSWING tsunami) cube's time steps. Errors when the window has neither. This is the natural frames value for a layer animation:

movie(fig; frames=nlayers(fig), name="cube") do fig, f
    set_layer!(fig, f.index)
end

oc_data_url(basename) -> String

Address of the L3 netCDF behind a browse image. The browse PNG is the L4 product and the data file is the L3 one OF THE SAME NAME, so this is a pure rename — there is no second catalogue to consult and no second lookup to get wrong:

…/showimages/MODISA/L3BRS/2026/0801/AQUA_MODIS.20260801.….nc.png     the image
…/cgi/getfile/AQUA_MODIS.20260801.….nc                              the grid

Unlike the freely readable browse images this one is behind Earthdata URS. Verified live (2026-08-03): /cgi/getfile/X → 301 → /getfile/X → 302 → /getfile/urs/?next=…, i.e. an OAuth login. So a download needs credentials — a ~/.netrc entry for urs.earthdata.nasa.gov (what curl, wget and GDAL's /vsicurl/ all read) or an OB.DAAC appkey. See oc_download_data.

oc_download_data(url; out="", nchunks=4, minchunk=8*1024*1024) -> String

Download the L3 netCDF at url into the cache and return its path ("" on failure).

Split into nchunks PARALLEL byte-range requests when the server both advertises Accept-Ranges: bytes and the file is big enough for the split to be worth its overhead; otherwise one plain stream. The chunks are fetched concurrently and written in order, so the result is byte-identical either way — the parallel path is a speed-up, never a different file.

Writes to .part files and renames only once every chunk is in, so an interrupted transfer can never leave a half-file in the cache to be reused as if it were whole.

oc_fetch_png(url; refresh=false) -> String

Local path of the browse image, downloading it once and reusing it afterwards. Returns "" when the download fails — a preview tile with no image is a normal outcome (offline, product gap), never an error worth aborting the dialog for.

Downloads to a .part file and renames only on success, so an interrupted transfer can never leave a truncated PNG in the cache to be served forever after.

oc_latest(inst, prod, period; n=2, from=today()) -> Vector{NamedTuple}

The n most recent images that exist on the server, newest first, as (start=Date, stop=Date, url=String). This is the "what is the end date?" answer the catalogue above deliberately does not hard-code: the mission rows know only when each instrument STARTED.

Walks the composite calendar backwards from from, probing candidate periods concurrently (the scan is entirely network-latency bound, so the tasks are worth it), then keeps the newest n hits in date order. Stops early at the instrument's first day, and returns fewer than n — possibly none — rather than inventing an entry.

oc_png_georef(prod) -> NamedTuple

Georeferencing of a browse image of prod: the L3 grid is global plate carrée, pixel-registered, with a plain 360/nx degree cell. Handed to the image builders so a preview tile can be promoted into a window as a real map rather than a bare picture.

orbit!(fig, azimuth, elevation=0; zoom=1) -> fig

Apply a relative VTK camera orbit to one InteractiveGMT window and render it. This is the simplest movie callback primitive; azimuth and elevation are degrees and zoom > 0 is multiplicative.

poly2fv(D::Vector{<:GMTdataset}; cmap=:turbo, zscale=:auto, vfrac=0.2, vexag=:auto,
		isgeog=false, ncolor=256, triangulate=false) -> GMTfv

Fold a vector of closed 3-D polygons into a single coloured GMTfv ready for view_fv — one mesh face per polygon, any corner count. Each polygon needs x y z columns; a repeated closing vertex is dropped. Faces are coloured by their mean z through the GMT colormap cmap. Pass triangulate=true to fan-split every polygon into triangles (concave / non-planar polys).

profile_to_xyplot(fig) -> QtXYPlot

Open the current Profile of a 3-D viewer window fig (a Ctrl+left-drag elevation profile, or a downloaded tide series — whatever its bottom-dock Profile panel shows) in a standalone X,Y plot tool window, with its Object Manager, Analysis menu and save. The programmatic twin of the panel's right-click "Open in X,Y plot tool". fig is any 3-D viewer handle (QtFigure/…).

remove_annotation!(fig, id) -> Bool

Remove one movie label or progress indicator by the id its constructor returned. Removing it from Scene Objects (its row's Remove) does the same thing; both go through the viewer's own remove, so the host registry cannot outlive the element.

replace_grid!(fig::QtFigure, G::GMTgrid; name="", zrange=nothing) -> fig

Replace the base grid in a live InteractiveGMT scene without rebuilding the window, preserving its camera, vertical exaggeration and overlays. Movie use intentionally requires the new grid to have the same x/y geometry as the current base grid; changing the mesh geometry while animating would invalidate a fixed camera and is outside the first movie backend. Pass zrange=(zmin,zmax) to keep a stable colour scale across frames instead of autoscaling each replacement grid independently.

fout, k = rtp3d(f3d, incl_fld, decl_fld, incl_mag, decl_mag; component=0)

Reduce a magnetic field anomaly map f3d to the pole, given the inclination/declination (degrees) of the ambient field (incl_fld, decl_fld) and of the magnetization (incl_mag, decl_mag).

component selects an alternative output instead of the plain RTP: 1 = X/North, 2 = Y/East, 3 = Z/Up component. Default 0 is the RTP.

f3d must be a GMTgrid (not a bare matrix): NaN holes break the FFT (they propagate through the whole transform, not just the hole), so f3d.hasnans is checked first and GMT.fillgaps runs automatically when needed, with a progress dialog telling the user why RTP is pausing to do that.

Returns the transformed grid fout and the wavenumber array k. fout comes back in the SAME memory order as f3d's own buffer — row-major (nx,ny) for a grid read in "TRB", column-major (ny,nx) for a "BCB" one. Nothing is transposed anywhere along the way.

save_png(path) -> Bool

Save a PNG of the most-recently-opened viewer window to path. Returns true on success.

save_png(fig, path; scale=1) -> Bool

Save the VTK render surface belonging to fig to path. Unlike save_png(path), this variant is figure-specific and therefore safe when several InteractiveGMT windows are open. scale is an integer VTK capture magnification (1 keeps the window's current pixel size).

R = sdg(G::GMTgrid; p=nothing, sign=:both)

Second Derivative in the direction of the Gradient of grid G, returned as a new GMTgrid with G's geometry.

p is the cubic-smoothing-spline parameter (0 = least-squares plane, 1 = interpolation); nothing takes csaps's own estimate, csaps_p_guess, off the Y axis — Mirone's default. sign is :both (keep everything), :positive (negative values zeroed) or :negative (positive values zeroed) — Mirone's three SDG menu entries.

selection(fig::QtPoints) -> Matrix

Return a copy of the point-cloud rows currently selected with Ctrl+right-drag in the viewer (x y z [...]), or an EMPTY matrix (0 rows, same columns) if none are selected (or the window is closed). Test with isempty.

set_layer!(fig, k) -> fig

Show layer k of the 3-D dataset fig is displaying, 1-based like MovieFrame.index and like both layer sliders in the UI (only the internal calls are 0-based).

Works on either kind of layered dataset the viewer has, through that kind's OWN existing switcher — _on_load_cube_layer for a plain netCDF cube, _aquamoto_slice for an NSWING tsunami cube. Neither is reimplemented here, and each is driven with the display options its own dialog last rendered with: the cube's "global min/max" choice, and the tsunami's Split Dry/Wet, colour scaling, transparency and shading toggles. So an animation looks exactly like the layer on screen — including, for a tsunami, the per-slice water relight the two-surface illumination law requires.

shapenc(fname::String, data; outer=nothing, inner=nothing, geog::Bool=true, srs::String="",
        desc::String="", version::String="", append::Bool=false, tag=nothing, tags=nothing,
        multiseg::Bool=false, point2D::Bool=false, polygon2D::Bool=false,
        polygon3D::Bool=false, polyline2D::Bool=false, polyline3D::Bool=false, f64::Bool=false)

Write data (a point swarm / polygon / polyline ensemble, or several of them) into fname as a SHAPENC netCDF4 file — a Julia port of Mirone's utils/shapenc.m. See this file's module docstring for the full write-up of what each option does and its exact scope; short form:

• data/outer/inner: file name, GMTdataset, Vector{<:GMTdataset}, Matrix{<:Real}, or Vector{<:Matrix{<:Real}}. outer/inner only apply to a single Point ensemble.
• geog/srs: geographic (lon/lat, default) vs projected (X/Y) coordinate names/units; srs overrides the written spatial_ref PROJ4/WKT string outright.
• desc/version: global Description/File Version attributes.
• append: add ensemble(s) to an existing SHAPENC file instead of overwriting it.
• tag: a String (ensemble name attribute) or (key,value) pairs (per-attribute), first ensemble only.
• tags: like tag, but a Vector with one entry PER ensemble (length(tags) == length(data)), applied to every ensemble instead of only the first — for a single batched call writing many independently-named ensembles at once (e.g. isocs.jl's shapefile batch, one name/fromage tag per feature). Takes priority over tag when both are given.
• multiseg: NaN-pack several segments into ONE ensemble instead of separate ones.
• point2D/polygon2D/polygon3D/polyline2D/polyline3D: force the geometry kind instead of auto-detecting it from a GMTdataset's .geom or the column count.
• f64: coordinate variables (lon/lat/z, PolyOUT/PolyIN) are written as netCDF Float32 by default; pass f64=true to write them as Float64 instead. Global/ensemble attributes (BoundingBox, tag numeric values, ...) are always Float64 regardless of f64.
• NOT ported: Douglas-Peucker dp simplification, raw GMT -b binary input, shapefile maxpoly chunking (see module docstring for why).

Examples

shapenc("acores.nc", [lon lat]; desc="Small ensemble isolated from main dataset")
shapenc("acores.nc", GMT.mat2ds([lon lat depth]))                      # 3-D, auto-detected
shapenc("acores.nc", swarm_xy; outer=poly_xy, inner=[hole1_xy, hole2_xy])
shapenc("acores.nc", swarm2_xy; append=true, tag="secondary cluster")
shapenc("many.nc", ["a.dat", "b.dat", "c.dat"])                        # 3 ensembles, 1 call
shapenc("track.nc", [seg1_xyz, seg2_xyz, seg3_xyz]; multiseg=true)     # 1 NaN-packed ensemble
shapenc("survey.nc", xy_meters; geog=false, srs="+proj=utm +zone=29 +datum=WGS84")
shapenc("track.nc", xy; polyline2D=true)                               # force geometry kind

shapenc2isoc(fname_nc::String, isoc_name::String, fname_out::String) -> String

Reverse of isoc2shapenc: given a SHAPENC file (single-isochron or grouped, e.g. isochrons_EU_NA.nc) and one isochron's short name (the file-stem ??? id isoc2shapenc tagged it with, e.g. "c13" — the netCDF variable/ensemble identity), write it back out as a Mirone-format isochron .dat: a "> " header line (the isochron/plate-pair name plus its KEY"v1 v2 ..." pole attributes) followed by tab-separated lon/lat rows — exactly the layout _isoc_read/isoc2shapenc read on the way in.

Pole attribute ORDER in the rebuilt header is FIN first, then STGn ascending, then anything else alphabetically (the convention every source data/isocs/*.dat file follows) — the original creation order isn't recoverable once the attributes are in a Dict (GMTdataset.attrib), so this reconstructs a clean, consistent header rather than guessing at byte order; the CONTENT (every key/value, to full precision) is exact regardless.

Example

shapenc2isoc("isochrons_EU_NA.nc", "c13", "c13_EU_NA_reconstructed.dat")

show_table(fig, data; name="")

Show data in the window's Data Viewer spreadsheet tab and bring that tab forward. fig is any viewer handle (QtFigure/QtPoints/QtFV); data is a GMTdataset (single or multi-segment Vector{GMTdataset}), a plain matrix, or a vector. name labels the tab (defaults to the dataset's header / "matrix" / "vector"). Returns fig.

Gs = spline_smooth(G::GMTgrid; p=nothing)

Smooth grid G with the same 2-D cubic smoothing spline the SDG is built on, and return the fitted SURFACE — Grid Tools > Spline Smooth, the port of Mirone's GridToolsSmooth_CB.

p is the smoothing parameter: 0 leaves the least-squares bilinear trend, 1 gives back the data untouched (an interpolating spline reproduces its own data), and the useful values sit just under 1. nothing takes csaps's own estimate, csaps_p_guess, off the Y axis — Mirone's default.

stereo!(fig, on=-1) -> Bool

Toggle red/cyan anaglyph stereo on a viewer window (use cheap red/cyan 3-D glasses to see real depth on the relief). on=true enables, on=false disables, default -1 flips the current state. Sets the stereo type to anaglyph so it actually renders on a normal monitor. Returns the new state (true = on). fig is any viewer handle (QtFigure/QtPoints/QtFV).

stickplot(t, u, v; scale=:auto, color=nothing, title="Stick diagram", kwargs...) -> QtXYPlot
stickplot(t, azimuth; mag=nothing, kwargs...) -> QtXYPlot

Draw a stick (vector) diagram: at each t a vector is plotted from the y=0 baseline. Give the vectors as (u, v) components, or as azimuth degrees (oceanographic: 0° = up/North, clockwise) with optional mag (default 1). scale sizes the sticks (:auto ≈ 5 % of the time span per full-magnitude vector). Returns a QtXYPlot; extra keywords (xlabel, ylabel, xtime, name) pass through.

t  = collect(0:0.5:48)                 # hours
az = 90 .+ 60 .* sin.(2π .* t ./ 12)   # tide-turning current direction
stickplot(t, az; mag=1 .+ 0.3 .* cos.(2π .* t ./ 12), title="Current sticks", xlabel="hour")

InteractiveGMT.update!()

Pull the latest InteractiveGMT source in place (fast-forward only) and rebuild the binaries. Only works for a ] dev-installed checkout — a plain Pkg.add install should use Pkg.update("InteractiveGMT") instead.

Show the built-in synthetic demo surface (no grid needed).

view_fv(name::AbstractString; color=true, cmap=:turbo, edges=false, geographic=nothing,
		title="", solid_kwargs...)

Show a NAMED GMT solid from the SOLIDS catalogue ("cube", "sphere", "torus", "icosahedron", "octahedron", "dodecahedron", "tetrahedron", "cylinder", "revolve", "loft", "extrude"). The solid takes its OWN parameters — any kwarg that is NOT a viewer keyword is forwarded untouched to the GMT generator:

view_fv("cube"; r=3)                 # r = circumradius (centre→vertex)
view_fv("sphere"; n=4)               # sphere's own subdivision level
view_fv("torus"; R=8, nx=200, edges=true)
view_fv("revolve"; curve=mycurve)    # your own profile (else a demo profile)

color behaves as in view_fv(::GMTfv): true (default) = FACETED per-face colour by mean z through cmap with a MATCHING colorbar; false = smooth per-vertex z; :explicit = the solid's own baked colours (no colorbar). The remaining viewer kwargs (cmap, edges, geographic, title) behave the same.

view_grid(G::GMTgrid; cmap=:auto, drape=nothing, outside=:shademesh, outside_color=200,
		  title="i'GMT", geographic=nothing)

Show a GMT.jl grid in the Qt + VTK viewer. Returns a QtFigure handle immediately; the window stays live while you keep using the REPL. Pass the handle to add! to add elements (lines/points) to this window later. cmap is any GMT colormap name (e.g. :geo, :turbo, :rainbow, :roma), applied LINEARLY over the grid's z range via makecpt; pass nothing for the built-in ramp. The default :auto picks :geo for topo/bathymetry grids (those GMT tags with cpt == "geo") and :turbo for everything else. drape is an optional GMTimage textured over the surface instead of the CPT colouring.

outside controls the grid area the drape image does NOT cover (mirrors GMTF3D):

• :shademesh (default) — flat outside_color fill (uncovered reads as the shaded surface).
• :shade — flat outside_color fill.
• :transparent — see-through; the CPT-coloured base surface shows through.

outside_color is a grey 0-255 int or an (r,g,b) tuple (0-255 ints or 0-1 floats).

The surface mesh (wire edges) is HIDDEN by default; press e in the viewer to toggle it on/off (works on both the base surface and any drape).

triangulate (default true) builds the surface from 2 triangles per grid cell (diagonals, GMTF3D-style); pass false for a single quad per cell.

data overlays a GMTdataset (single or multi-segment Vector{GMTdataset}) on the surface, drawn as mode=:lines (default) or mode=:points. Its z comes from column 3 if present, else is sampled off the grid so it drapes on the relief. data_color is a grey 0-255 int, an (r,g,b) (0-255 ints or 0-1 floats), or nothing (black lines / red points). data_size sets the line width or point size in px (0 = default). Right-click an overlay for a context menu to change its colour, line style/width (lines) or size and round/square (points).

vcurtain hangs a Fledermaus-style vertical image curtain (seismic / midwater profile) along an XY track through the scene — one spec NamedTuple, or a vector of them: (; image, path, zrange, spacing=:distance, flipv=false, clip=false, clip_n=300) (same fields as add_curtain!). E.g. view_grid(G; vcurtain=(; image="sect.jpg", path=track, zrange=(-10000,0), clip=true)).

geographic is auto-detected (override with true/false). For geographic grids the vertical exaggeration is referenced to metres (1°lat ≈ 111111 m, 1°lon = that × cos(mid-lat)); z assumed metres.

view_image(I::GMTimage; title="i'GMT", geographic=nothing, axes=nothing)

Show a bare GMTimage (no elevation) in the viewer: a flat plane textured with the image, opened maximized in a top-down orthographic map. Returns a QtImage handle immediately (the window stays live while you use the REPL). The status-bar readout shows the pixel colour (rgb = R G B) under the cursor instead of a z value. geographic is auto-detected (GMT.isgeog); override with true/false. Also reachable as iview(I).

view_points(D; cmap=:turbo, pointsize=4, pickcolor=(0.83,0.83,0.83),
			geographic=nothing, title=...)

Show a point cloud — a GMTdataset or an N×≥3 matrix of x y z [...] rows — in the Qt + VTK viewer, colouring each point by its z through the GMT colormap cmap (any GMT name, e.g. :turbo, :roma, :geo; nothing = the built-in ramp). Returns a QtPoints handle immediately; the window stays live while you keep using the REPL.

Ctrl+right-drag a box over the cloud to select points (TOGGLE — re-dragging the same box deselects; Ctrl+Z undoes the last change). Plain right-drag stays the dolly. The selected points are highlighted in pickcolor and kept for you — read them back with selection, which returns a copy of the picked x y z [...] rows (or nothing).

• pointsize — point size in px.
• pickcolor — highlight colour for selected points: an (r,g,b) (0-255 ints or 0-1 floats) or a grey number.
• geographic — auto-detected for a GMTdataset (override with true/false); treats x,y as degrees and z as metres for a physically-true vertical scale.

wait_windows()

Block (yielding, so the Qt pump keeps running) until every viewer window is closed. Useful at the tail of a julia script.jl run, where there is no REPL to keep the process alive.

warm_register(tool::String, body::Function)

Declare how to warm tool up. body takes no arguments, runs the tool's own maths on tiny data and must not touch the live scene. Called from the tool's _register_* function.

warm_start(tool::String)

Kick off tool's warm-up in the background and return immediately. No-op if the tool has no registered body, or if it was already started once in this session.

warm_wait(tool::String)

Block until tool's warm-up has finished, if one is running. Call it at the top of the tool's compute path so the warm-up and the real work never run at the same time.

xtime!(p::QtXYPlot, mode) -> QtXYPlot

Format the X axis as time, reading X as Unix epoch seconds. mode is :linear (plain numbers), :date (auto by span), :date_ymd (yyyy-mm-dd), :time (HH:MM), :decyear (decimal year) or :doy (decimal day-of-year). Ticks auto-update on zoom/pan.

xyinfo!(p::QtXYPlot, html::AbstractString) -> QtXYPlot

Set (or clear, with "") a rich-text header strip above an X,Y plot window's chart – e.g. the Tide tool's "Next High Tide … / Time now … / Next Low Tide …" lines. Basic HTML (<b>, <br>, inline color: spans) is supported (Qt rich text). Hidden when empty.

xynowcross!(p::QtXYPlot, x, y; color=:red, size=10, width=2, name="Now") -> QtXYPlot

Add a screen-constant "+" cross at data point (x, y) – e.g. a "current time" indicator on a time-series plot. Unlike add!(...; marker=:plus), this is NOT a vtkPlotPoints marker (VTK's marker rendering reuses the plot's own pen width to draw the glyph, so a marker-only series has no independently-controllable thickness at all): it's a real 2-segment line path whose data-space half-lengths are recomputed every render from the actual per-axis pixel scale, so both arms stay visually equal-length on screen no matter how different the X/Y data ranges are, and it keeps that shape across zoom/pan/resize. size (half-arm-length) and width (stroke thickness) are BOTH in points, not raw screen pixels – a physical, DPI-independent unit (same reasoning GMT itself uses pens in points, never px), converted internally at 96/72 dpi same as add_symbols!. Both are also live-editable afterward via the series' own "Line properties…" dialog (Object Manager right-click) – note that dialog's spinbox is px internally (VTK's own units), so it will show the ~1.33x-scaled pixel value, not the points figure this call took.

xyplot(x, y; name="", color=nothing, linewidth=0, title="", xlabel="X", ylabel="Y") -> QtXYPlot

Open a standalone X,Y plot window and draw the (x, y) series. y may be a matrix whose columns are separate lines sharing the same x. color accepts a name (:red, "blue"), a 0–255 / 0–1 triple, or nothing for the default. xlabel/ylabel set the axis titles. Returns a live QtXYPlot handle; add more lines with add!. Non-blocking.

t = range(0, 4π; length=400) |> collect
p = xyplot(t, sin.(t); name="sin", title="demo", ylabel="amplitude")
add!(p, t, cos.(t); name="cos", color=:blue)