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 (_isgeographic: the CRS, else GMT.guessgeog's lon/lat range test); 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!(fig::QtFigure, G::GMTgrid; name="grid", cmap=:auto, drape=nothing, samezscale=false)

Add a second grid to the window fig as its own layer, exactly as dropping that grid's file on the window would: it gets its own Scene Objects handle, its own colour bar and axes, and becomes the layer on display (the others are unchecked; tick them back with setvisible!).

drape (a GMTimage over the grid's box) is painted on this grid's surface instead of its CPT colours, as iview(G; drape=I) does for the window's own grid.

samezscale=true draws it on the vertical scale of fig's own grid, for the SAME quantity (a basement surface under the topography, both elevations in metres) — the grid menu's Same vertical scale as … item. It is set automatically when both grids name the same z unit. Returns fig.

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

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

kind=:bar draws it as a BAR graph (what the Analysis menu's Histogram / Bar graph items use) instead of a polyline; barwidth is then the bar width in x data units (0 = derive it from the data: 90% of the median x spacing), and linewidth becomes the bars' outline thickness in px.

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. Give a GMTgrid instead of true to cut it to THAT surface (e.g. a basement under the topography).

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_isosurface!(fig::QtFigure, C::GMTgrid; level, color=:orange, opacity=1.0, name="",
                samezscale=true)

Add to the window fig the surface where the 3-D cube C crosses the value level — an iso-surface, as a mesh layer with its own Scene Objects row. C is a GMT cube (ndims(C.z) == 3) whose layers sit at the heights C.v, which may be irregular. Give C.v in the same vertical units as fig's own grid.

color is the surface colour (a name or an (r,g,b)), opacity its opacity from 0 to 1. samezscale=true draws it on the vertical scale of fig's own grid, so it stands at its true depth under the topography (see add!). Like every added layer it becomes the layer on display; tick the others back on with setvisible!. Returns fig.

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.

Shift+left-drag (or 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.

selection() -> Matrix{Float64}

The points selected in the LAST point cloud you selected in — Shift+left-drag (or Ctrl+right-drag) a box over any cloud, however it was opened (view_points, a dropped .laz, an MB-System swath file, File > Open) — as an n×3 matrix of x y z rows. Empty (0×3) when nothing is selected or that window is closed.

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.

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

The depth grid of cubegrid_all, same arguments.

cubegrid_all(data; region, inc, kwargs...) -> NamedTuple

Grid scattered soundings with CUBE (Combined Uncertainty and Bathymetry Estimator, Calder & Mayer, CCOM/JHC) and return every grid it produces: (depth, uncertainty, n_hypotheses, ratio, n_points), each a GMTgrid on the same nodes.

• depth: the depth of the hypothesis chosen at each node (in the input's z convention, see zdown)
• uncertainty: CUBE's uncertainty of that depth at 95% confidence
• n_hypotheses: how many depth hypotheses the node holds (more than 1 = conflicting soundings)
• ratio: hypothesis strength ratio, 0 with a single hypothesis, larger = less sure of the choice
• n_points: soundings in the chosen hypothesis

data may be a GMTdataset, a vector of them, an N×3 matrix, x, y, z vectors, or the PATH of MB-System swath data: a datalist (.mb-1) or a swath file (.mbNN, .all, .kmall, .s7k, .gsf, ...), read through MB-System's MBIO. Swath soundings become longitude, latitude and ELEVATION, so the depth grid comes back negative below sea level, like every other grid in iGMT.

Geometry

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

Either may be left out: it is then what GMT would choose for the data (its limits, estimate_RI).

Options

• iho_order = :order1a IHO S-44 order: :exclusive, :special, :order1a, :order1b, :order2. Bounds how far a sounding spreads and sets the default uncertainty.
• method = :local hypothesis selection: :local (guided by the nearest single-hypothesis node), :prior (most soundings), :posterior (both), :predicted.
• tvu = nothing sounding vertical uncertainty at 95% as (a, b): sqrt(a^2 + (b*depth)^2) m.
• thu = nothing sounding horizontal uncertainty at 95% as (a, b): a + b*depth m. nothing = the limits of iho_order.
• variance = :cube reported uncertainty: :cube (posterior), :input (sounding spread), :max.
• noqueue = false skip CUBE's median pre-filter queue.
• paramfile = "" a bathycube CubeParameters JSON file; the options above override it.
• zdown = false false: z is elevation (GMT convention, negative below sea level); true: z is depth, positive down (MB-System convention).
• geographic = nothing true/false, or nothing to let GMT guess from the data.
• registration :gridline (default) or :pixel.
• verbose = false CUBE's per-sounding DEBUG trace (very long).
• flag_k = nothing CUBE as a sounding filter: a number k also returns flagged, one Bool per input sounding, true where it misses CUBE's depth at its node by more than k standard deviations (sounding and node together). nothing: flagged is nothing.

Every option also accepts the string form the Interpolate dialog sends.

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).

Satellite(tle::TLE; model = 0)

A propagator for one TLE. Parsing and the model set-up happen once, here, so propagating N epochs costs N model steps and not N initialisations.

model picks the analytic model by name (:SGP, :SGP4, :SDP4, :SGP8, :SDP8); the default 0 lets the C side choose, which is what you want — it uses the near-earth or deep-space model according to the orbit's actual period, not according to what the TLE claims. Published TLEs almost all claim type 0, so without that a geostationary or Molniya orbit would be propagated with the wrong model and be wrong by hundreds of kilometres.

The C handle is freed by a finalizer, and close! frees it early if you want determinism.

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. uv (east, north per point) is empty unless the layer is an ARROW field, whose world length is then worldSize.

TLE(name, line1, line2)

One two-line element set, with the (optional) name line that precedes it in a TLE file. line1/line2 are kept verbatim — the C side parses them, so nothing here has to know the column layout, and a file round-trips unchanged.

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!(fig::QtFigure, G::GMTgrid; name="grid", cmap=:auto, drape=nothing, samezscale=false)

Add a second grid to the window fig as its own layer, exactly as dropping that grid's file on the window would: it gets its own Scene Objects handle, its own colour bar and axes, and becomes the layer on display (the others are unchecked; tick them back with setvisible!).

drape (a GMTimage over the grid's box) is painted on this grid's surface instead of its CPT colours, as iview(G; drape=I) does for the window's own grid.

samezscale=true draws it on the vertical scale of fig's own grid, for the SAME quantity (a basement surface under the topography, both elevations in metres) — the grid menu's Same vertical scale as … item. It is set automatically when both grids name the same z unit. Returns fig.

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

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

kind=:bar draws it as a BAR graph (what the Analysis menu's Histogram / Bar graph items use) instead of a polyline; barwidth is then the bar width in x data units (0 = derive it from the data: 90% of the median x spacing), and linewidth becomes the bars' outline thickness in px.

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. Give a GMTgrid instead of true to cut it to THAT surface (e.g. a basement under the topography).

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_isosurface!(fig::QtFigure, C::GMTgrid; level, color=:orange, opacity=1.0, name="",
                samezscale=true)

Add to the window fig the surface where the 3-D cube C crosses the value level — an iso-surface, as a mesh layer with its own Scene Objects row. C is a GMT cube (ndims(C.z) == 3) whose layers sit at the heights C.v, which may be irregular. Give C.v in the same vertical units as fig's own grid.

color is the surface colour (a name or an (r,g,b)), opacity its opacity from 0 to 1. samezscale=true draws it on the vertical scale of fig's own grid, so it stands at its true depth under the topography (see add!). Like every added layer it becomes the layer on display; tick the others back on with setvisible!. Returns fig.

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. srs names the referencing system x, y are in (e.g. lon/lat for a catalog); when it differs from the window's the points are reprojected and cut to its footprint first. Returns true if the layer was added.

aqua_pbr_release!()

Close the kept render windows. Call when the animation is over; the next call reopens them.

aqua_shade_image(bat, G; method_water, method_land, …) -> (img, mask, iw, il)

THE function. bat is the bathymetry, G the slice's stage; both as they were read, no copies, no blanking, no NaN.

method_* is the Illumination dialog's own numbering, per side:

2 GMT grdgradient classic -A<azim> -Nt 3 GMT grdgradient Lambertian -Es<azim>/<elev> 4 Lambertian with lighting -E<azim>/<elev>+a<amb>+d<diff>+p<spec>+s<shine> 5 Hillshade (grdimage) the classic reflectance with a gain 6 Hillshade (Lambert) -Es<azim>/<elev> with an ambient term

1 VTK (PBR) VTK's own render, captured

Method 1 is not a reflectance and is not computed here: it is VTK's PBR RENDER, whose material lives on an ACTOR (SetInterpolationToPBR + the IBL sky — applySurfStyle / applyShading, 40shading.cpp). Its half is therefore DISPLAYED and LIT through the Illumination tool's own door (`onhillshadewithmodel=1, the very request the dialog sends) and its pixels are taken with the capture that already exists (gmtvtkcapturerectrgb). Nothing of that maths is re-implemented, and it is NOT method 7 — 7 is the CPU Cook-Torrance bake (applyPBRShade`) that imitates the render per pixel, which lives in C++ and is a different picture.

Returns the combined image and, for inspection, the two halves' pictures as plain (row, col, band) RGB arrays.

catalina_benchmark1(scene; xmin=-200.0, xmax=20000.0) -> String

Open Catalina benchmark 1 in the iGMT window scene, AT ITS BEGINNING: the flume's bathymetry with the analytic solitary wave as the water surface at t = 0, clipped for display to x ∈ [xmin, xmax]. It builds two grids and writes a one-step cube — nothing is simulated, so the window is up immediately. Running the model is a separate, explicit step — the Aquamoto dialog's "Benchs" tab.

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.

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

The depth grid of cubegrid_all, same arguments.

cubegrid_all(data; region, inc, kwargs...) -> NamedTuple

Grid scattered soundings with CUBE (Combined Uncertainty and Bathymetry Estimator, Calder & Mayer, CCOM/JHC) and return every grid it produces: (depth, uncertainty, n_hypotheses, ratio, n_points), each a GMTgrid on the same nodes.

• depth: the depth of the hypothesis chosen at each node (in the input's z convention, see zdown)
• uncertainty: CUBE's uncertainty of that depth at 95% confidence
• n_hypotheses: how many depth hypotheses the node holds (more than 1 = conflicting soundings)
• ratio: hypothesis strength ratio, 0 with a single hypothesis, larger = less sure of the choice
• n_points: soundings in the chosen hypothesis

data may be a GMTdataset, a vector of them, an N×3 matrix, x, y, z vectors, or the PATH of MB-System swath data: a datalist (.mb-1) or a swath file (.mbNN, .all, .kmall, .s7k, .gsf, ...), read through MB-System's MBIO. Swath soundings become longitude, latitude and ELEVATION, so the depth grid comes back negative below sea level, like every other grid in iGMT.

Geometry

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

Either may be left out: it is then what GMT would choose for the data (its limits, estimate_RI).

Options

• iho_order = :order1a IHO S-44 order: :exclusive, :special, :order1a, :order1b, :order2. Bounds how far a sounding spreads and sets the default uncertainty.
• method = :local hypothesis selection: :local (guided by the nearest single-hypothesis node), :prior (most soundings), :posterior (both), :predicted.
• tvu = nothing sounding vertical uncertainty at 95% as (a, b): sqrt(a^2 + (b*depth)^2) m.
• thu = nothing sounding horizontal uncertainty at 95% as (a, b): a + b*depth m. nothing = the limits of iho_order.
• variance = :cube reported uncertainty: :cube (posterior), :input (sounding spread), :max.
• noqueue = false skip CUBE's median pre-filter queue.
• paramfile = "" a bathycube CubeParameters JSON file; the options above override it.
• zdown = false false: z is elevation (GMT convention, negative below sea level); true: z is depth, positive down (MB-System convention).
• geographic = nothing true/false, or nothing to let GMT guess from the data.
• registration :gridline (default) or :pixel.
• verbose = false CUBE's per-sounding DEBUG trace (very long).
• flag_k = nothing CUBE as a sounding filter: a number k also returns flagged, one Bool per input sounding, true where it misses CUBE's depth at its node by more than k standard deviations (sounding and node together). nothing: flagged is nothing.

Every option also accepts the string form the Interpolate dialog sends.

datetime(jd::Float64) -> DateTime

The inverse of jd, to millisecond resolution.

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 GMT.jl script and return its text. With path, the script — and nothing else — is written there. A layer that exists only in memory is fetched by the script from the live window, so such a script runs while that window is open.

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.

groundtrack(sat; start, stop, step) -> Vector{GMTdataset}
groundtrack(sat, when)              -> Vector{GMTdataset}

The sub-satellite track, as a multi-segment dataset ready to plot: columns are lon, lat, alt_km, time (Julian Day), and the track is cut at the dateline so it draws as a map track instead of streaking back across the plot.

With keywords, start defaults to the TLE's own epoch (a TLE is only good for a few days either side of it), stop to one orbital period later — i.e. exactly one revolution — and step to 30 seconds, which keeps a LEO track smooth.

groundtrack(sat; start = now(UTC), stop = now(UTC) + Hour(6), step = Minute(1))

True if this CRS carries any referencing at all.

install_mbsystem_plugin()

Download MB-System's GMT supplement from the mbsystem-latest release of joa-quim/MB-System into <InteractiveGMT>/mbsystem and load it into GMT. Re-running it replaces the installed copy. Geophysics > MB-System > Install as plugin calls this.

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.

jd(t::DateTime) -> Float64

Julian Day (UTC) of a DateTime.

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.

mbedit(file=""; format=0, esf=:ask) -> Bool

Open the swath bathymetry editor, a port of MB-System's mbedit: the pings of a swath sonar file drawn as a waterfall of across-track profiles, whose soundings are flagged and unflagged with the mouse (Toggle, Pick, Erase, Restore, Grab, Info modes) and the same key macros, filters and views as mbedit. Edits go to the file's edit save file (file.esf) and are recorded for mbprocess, exactly as mbedit does.

• file: a swath file, or a datalist with format=-1. Empty opens the editor with File > Open.
• format: the MB-System format id; 0 guesses it from the file name.
• esf: what to do with an edit save file left by an earlier session: :ask (mbedit's dialog), true (apply it, mbedit -S) or false (start from the file's own flags).

The editor reads swath data through MB-System's MBIO library, loaded at run time: the one GMT loads with the MB-System supplement it is configured with (GMT_CUSTOM_LIBS). To pick another, set ENV["INTERACTIVEGMT_MBIO"] to its path, or point to it when the editor asks (the answer is kept in iGMT.ini). It is also on the Tools menu, as "Swath editor (mbedit)".

Returns true when the editor is open, with the file loaded if one was given.

mbedit("TN136HS.309.snipped.mb11")
mbedit("survey.mb-1"; format=-1)        # a datalist

mbeditviz(file=""; format=0, browse=false) -> Bool

Open the bathymetry editor and patch test tool, a port of MB-System's mbeditviz. Swath files are listed, loaded and gridded together; the grid and every file's navigation are shown on a survey map (an InteractiveGMT window); the soundings of a shape drawn on that map (a Region, an Area along a line, or the pings of the Navigation inside it) open in a 3-D editor where they are flagged and unflagged (Toggle, Pick, Erase, Restore, Grab, Info, and mbedit's key macros), and where roll, pitch, heading, time lag and sound speed corrections are tried (patch test) and optimized. Edits go to each file's edit save file (file.esf) and its mbprocess parameter file, as mbeditviz does.

• file: a swath file, or a datalist with format=-1. Each file needs its .inf (mbinfo) file.
• format: the MB-System format id; 0 guesses it from the file name.
• browse: look only (mbeditviz's Browse Only mode): nothing is written.

mbeditviz needs MB-System 5.8.x's MBIO library, found as the swath editor finds it (ENV["INTERACTIVEGMT_MBIO"], iGMT.ini, the PATH, or asked). It is also on the Tools menu, as "Bathymetry editor and patch test (mbeditviz)".

mbeditviz("survey.mb-1"; format=-1)

mbgrdviz(file=""; fig=nothing) -> Bool

Open the survey planning and display tool, a port of MB-System's mbgrdviz, on InteractiveGMT windows. A grid shown in an InteractiveGMT window is its view: site, route, vector, navigation and swath files open into that window as its own elements (each route a polyline, each site a symbol, each navigation line an overlay), with their Scene Objects rows; routes and sites drawn in the window with its Polyline and Symbols tools are mbgrdviz routes and sites. Sites and routes are saved in mbgrdviz's formats (route, reversed route, Risi scripts, degrees and decimal minutes, Hypack LNW, Greensea YML, TECDIS LST, Kongsberg DP, SIS ASCIIPlan), a profile along a route is saved, survey lines are generated over an area (a two-point line drawn in the window plus a width), a region (a drawn rectangle) is opened as a new window, and the checked navigation is opened in the ported swath editors (mbedit, mbeditviz, mbvelocitytool).

• file: a grid to open, as mbgrdviz -I does: into fig's window when it is empty, else a new window.
• fig: the window to bind (a figure returned by view_grid and friends).

It reads swath files with MB-System's MBIO library, found as the swath editor finds it (ENV["INTERACTIVEGMT_MBIO"], iGMT.ini, the PATH, or asked). It is also on the Tools menu of every window, as "Survey planning (mbgrdviz)".

fig = view_grid(G);  mbgrdviz(; fig)

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)

mbnavadjust(project=""; fig=nothing) -> Bool

Open the navigation adjustment tool, a port of MB-System's mbnavadjust: the bathymetry of overlapping and crossing swath lines is made to agree by adjusting their navigation. The files of a project are cut into sections; where two sections overlap they form a crossing, at which an offset — a tie — is set by hand (dragging one section's contours over the other's) or by correlation (Auto-Pick). An inversion turns the ties into a smooth navigation adjustment for every file, which mbprocess then applies.

• project: an mbnavadjust project (.nvh) to open, as mbnavadjust -I project; empty: File > New or File > Open in the tool.
• fig: the viewer window the tool belongs to (it parks in its Scene Objects when closed or minimised).

The project's programs (mbdatalist, mbprocess, mbgrid) run as MB-System's GMT modules, in this process; View > Visualize Survey opens the project grid in a viewer window with the navigation and the ties on it. It is also on Geophysics > MB-System, as "MBnavadjust". The swath files are read through MB-System's MBIO library, the same one the swath editor (mbedit) uses and found the same way.

Returns true when the tool is open (and the project, when one is given).

mbnavadjust("C:/surveys/adjust/Project.nvh")

mbnavedit(files...; format=0, browse=false, run_mbprocess=false, use_ping_data=false,
          strip_comments=false) -> Bool

Open the navigation editor, a port of MB-System's mbnavedit: the navigation of a swath file shown as time series — time between fixes, longitude, latitude, speed, heading and sonar depth — where bad fixes are selected with the mouse and repaired by interpolation, by the speed or course made good, or by a navigation model (Gaussian mean, dead reckoning, smooth inversion).

• files: swath files or datalists (-I). Every file joins the editor's file list and the first one is loaded; Done moves on to the next.
• format: their MB-System format id (-F), one for all or a vector, one per file; 0 guesses it from the file name, -1 reads a datalist.
• browse: look only, nothing is written (-D). Otherwise the edited navigation goes to <file>.nve and is set in the file's mbprocess parameter file.
• run_mbprocess: run mbprocess on a file when it is finished (-X); strip_comments passes it -N (-N).
• use_ping_data: take the navigation from the survey pings instead of the navigation records (-P).

It is also on Geophysics > MB-System, as "MBnavedit", and on each MBgrdviz ship track's right-click menu. The files are read through MB-System's MBIO library, the same one the swath editor (mbedit) uses and found the same way (ENV["INTERACTIVEGMT_MBIO"], iGMT.ini, the PATH, or asked).

Returns true when the editor is open with the first file loaded (or open and empty, with no file).

mbnavedit("TN136HS.309.snipped.mb57")
mbnavedit("survey.mb-1"; format=-1, run_mbprocess=true)

mbprocess_dialog(file="") -> Bool

Open Geophysics > MB-System > "Process swath data (mbprocess)": MB-System's mbset and mbprocess behind a dialog, on a swath file or a datalist (file, optional). The bathymetry edits saved by mbedit / mbeditviz / CUBE (the edit save file) are switched on or off in each file's parameter file (file.par), and Process runs mbprocess on every file, its report shown in the dialog's log. Needs MB-System's GMT supplement (on Linux and macOS: Geophysics > MB-System > Install as plugin).

With fig (a viewer window) the dialog belongs to that window, as when it is opened from its menu: closing or minimising it parks it in the window's Scene Objects.

mbvelocitytool(swath=""; format=0, edit_svp="", display_svp="") -> Bool

Open the sound velocity profile editor, a port of MB-System's mbvelocitytool: water sound velocity profiles (SVPs) drawn as depth against velocity, an editable profile whose nodes are dragged (left button), added (middle) and deleted (right) with the mouse, and the pings of a swath file raytraced through it. The tool shows the rays of the first ping and the mean bathymetry residual of every beam: a profile that is right leaves the residuals flat.

• swath: a swath sonar file (-I). Its pings are raytraced through the editable profile; if none is loaded yet, the default one is made for it. The Levitus annual mean profile at the file's first position, and any <swath>_NNN.svp written by mbsvplist, are added as display profiles.
• format: its MB-System format id (-F); 0 guesses it from the file name.
• edit_svp: a profile to edit (-W), as lines of depth velocity (# lines are comments).
• display_svp: a profile to show for comparison (-S).

The File menu saves the edited profile, <swath>.svp and the beam residuals as static offsets (<swath>.sbo, .sbao), and sets them in the swath file's mbprocess parameter file, exactly as mbvelocitytool does. It is also on the Tools menu, as "Sound velocity editor (mbvelocitytool)".

The swath file is read through MB-System's MBIO library, the same one the swath editor (mbedit) uses and found the same way (ENV["INTERACTIVEGMT_MBIO"], iGMT.ini, the PATH, or asked).

Returns true when the tool is open with every given file loaded.

mbvelocitytool("TN136HS.309.snipped.mb11")
mbvelocitytool("survey.mb58"; edit_svp="ctd_cast.svp")

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.

Orbital period, in minutes.

plot_groundtrack!(fig, sat; color = nothing, name = "", kw...)

Draw sat's ground track into an open iGMT window and register it in Scene Objects.

fig is a window handle (a QtFigure, or the raw pointer). Keywords not listed are passed to groundtrack, so start, stop, step and revolutions all work here.

This is a VECTOR overlay landing on whatever is already displayed, so — per SACREDLAW.md's vector-import law — it does NOT reframe the axes and does not spawn a set of its own: it goes on top of the map that is already there. It reaches the scene through `adddatasetto_scene`, the same function every other vector import uses, which is what gives it its Scene Objects row (one row per satellite, carrying every dateline segment) with properties and Remove.

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/…).

propagate(sat, when) -> (pos, vel)

State vectors in the TEME frame: pos in km and vel in km/s, each a 3×N matrix (one column per epoch). when is a DateTime, a vector or range of them, or Julian Days as Float64.

An epoch the model cannot solve comes back as NaN rather than as a plausible-looking point — a long run is not aborted by one bad step.

propagate_ecef(sat, when) -> Matrix

Earth-fixed (ECEF) positions in km, 3×N. Same time forms as propagate.

read_tle(src) -> Vector{TLE}

Read every TLE in src, which is either a path to a TLE file or a string holding the TLE text itself (what a Celestrak/Space-Track download hands back). Two- and three-line formats are both read: a non-TLE line immediately above a "1 …" line is taken as the object's name, and anything else — blanks, comments, prose — is skipped.

Malformed sets are skipped rather than thrown on: these files come off the network, and one bad entry should not cost the other nine hundred.

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.

selection() -> Matrix{Float64}

The points selected in the LAST point cloud you selected in — Shift+left-drag (or Ctrl+right-drag) a box over any cloud, however it was opened (view_points, a dropped .laz, an MB-System swath file, File > Open) — as an n×3 matrix of x y z rows. Empty (0×3) when nothing is selected or that window is closed.

selection_ids() -> Vector{Int}

The 1-based indices, into the cloud's own points, of the rows selection() returns.

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.

setopacity!(fig, alpha; layer="")

Set a raster layer's opacity, from 0 (invisible) to 1 (opaque): the window's own grid, or the added layer called layer (its drape fades with it). A half-transparent topography shows what lies under it. Returns fig.

setvisible!(fig, name, on=true; layer="")

Check (on=true) or uncheck the Scene Objects row called name — the same as clicking its box. The window's own grid is the row "Surface". layer picks the row inside that layer's group, for the rows every layer carries under the same name: setvisible!(fig, "Axes", false; layer="Basement") hides the basement's own axes. Returns fig.

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")

subpoint(sat, when) -> (lon, lat, alt)

The sub-satellite point: geodetic longitude and latitude in degrees (WGS84) and height above the ellipsoid in km, as three vectors.

tsupbr(path; k=nothing, var="z", …) -> GMTimage

READ A TSUNAMI SLICE AND SHOW IT COMPOSED WITH METHOD 1 (VTK PBR) ON BOTH HALVES:

using InteractiveGMT
tsupbr("C:/v/tsu/tsu_ocean2/tsu_time.nc")
tsupbr(path; k = 40, azim_land = 300.0)

It is tsushade with both methods 1 — same reader, same split, same combine. Each half is rendered by VTK with its PBR material and captured; the two captures are combined by the dry/wet mask.

tsushade(path; k=nothing, var="z", method=2, …) -> GMTimage

READ A TSUNAMI SLICE, BUILD THE COMBINED PICTURE, AND SHOW IT. One call, nothing else to set up:

using InteractiveGMT
tsushade("C:/v/tsu/tsu_ocean2/tsu_time.nc")                  # middle layer
tsushade("C:/v/tsu/tsu_ocean2/tsu_time.nc"; k = 40)          # layer 41 (k is 0-based)
tsushade(path; method_water = 3, method_land = 6, azim_land = 300.0)
tsushade(path; savefile = "C:/v/combined.png")               # …and write it out

method sets both sides at once; method_water / method_land override either. The image is the one aqua_shade_image makes — the two halves lit apart and combined by the dry/wet mask — and it is the same picture Aquamoto shows. It is displayed with GMT's own imshow and returned, so it can be looked at, written, or passed on.

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 (_isgeographic: the CRS, else GMT.guessgeog's lon/lat range test); 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.

Shift+left-drag (or 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.

wcdviewer(file="")

Open the water column viewer (Geophysics > MB-System > Water column viewer), with a Kongsberg .kmwcd/.kmall file loaded when one is given.

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)

@tool_error "message" key=value…

Report a failure from a code path that has NO window handle to log into (a helper below the tools, a load-time step, a background task). Prints at ERROR severity — it IS an error, it was raised and caught — and records it in the failure sink, so a test that does not claim it fails the run.

@warn was what every one of these used to be, and that is precisely how they stayed invisible: severity said "carry on", nothing recorded them, and the suite went green over them.