Add 3D cube ex

documentation/all_docs_ref/all_refs.md

@@ -43,15 +43,18 @@ its use requires resorting to the \myreflink{Monolithic} mode.
 
 ## Utility functions
 
-| | | | | | | | | | |
-|:-----|:----|:----|:----|:----|:----|:----|:----|:----|:----|
-| \myreflink{ablines} | \myreflink{append2fig} | \myreflink{blendimg!} | \myreflink{cart2pol} | \myreflink{cart2sph} | \myreflink{colorzones!} | \myreflink{cpt4dcw} | \myreflink{crop} | \myreflink{cubeplot} | \myreflink{date2doy} |
-| \myreflink{delrows!} | \myreflink{doy2date} | \myreflink{imagesc} | \myreflink{inwhichpolygon} | \myreflink{lelandshade} | \myreflink{coastlinesproj} | \myreflink{cubeslice} | \myreflink{gadm} | \myreflink{geocoder} | \myreflink{geodetic2enu} |
-| \myreflink{getbyattrib} | \myreflink{gmtread} | \myreflink{gmtwrite} | \myreflink{graticules} | \myreflink{gridit} | \myreflink{gunique} | \myreflink{image_alpha!} | \myreflink{image_cpt!} | \myreflink{imshow} | \myreflink{ind2rgb} |
-| \myreflink{info} | \myreflink{isnodata} | \myreflink{lelandshade} | \myreflink{linearfitxy} | \myreflink{magic} | \myreflink{mat2ds} | \myreflink{mat2grid} | \myreflink{mat2img} | \myreflink{mosaic} | \myreflink{ODE2ds} |
-| \myreflink{orbits} | \myreflink{pca} | \myreflink{plotgrid!} | \myreflink{plotyy} \myreflink{pol2cart} | \myreflink{polygonlevels} | \myreflink{rasterzones!} | \myreflink{regiongeog} | \myreflink{rescale} | \myreflink{slicecube} | \myreflink{sph2cart} |
-| \myreflink{stackgrids} | \myreflink{ter2cart} | \myreflink{theme} | \myreflink{uniqueind} | \myreflink{vecangles} | \myreflink{weather} | \myreflink{whereami} | \myreflink{wmsinfo} | \myreflink{wmsread} | \myreflink{wmstest} |
-| \myreflink{worldrectgrid} | \myreflink{worldrectcoast} | \myreflink{worldrectangular} | \myreflink{xyzw2cube} | \myreflink{yeardecimal} | \myreflink{zonal_stats} | | | | |
+| | | | | | | | |
+|:-----|:----|:----|:----|:----|:----|:----|:----|
+| \myreflink{ablines} | \myreflink{append2fig} | \myreflink{blendimg!} | \myreflink{cart2pol} | \myreflink{cart2sph} | \myreflink{colorzones!} | \myreflink{cpt4dcw} | \myreflink{crop} |
+| \myreflink{cubeplot} | \myreflink{coastlinesproj} | \myreflink{cubeslice} | \myreflink{date2doy} | \myreflink{delrows!} | \myreflink{doy2date} | \myreflink{gadm} | \myreflink{geocoder} |
+| \myreflink{geodetic2enu} | \myreflink{getbyattrib} | \myreflink{gmtread} | \myreflink{gmtwrite} | \myreflink{graticules} | \myreflink{gridit} | \myreflink{gunique} | \myreflink{imagesc} |
+| \myreflink{inwhichpolygon} | \myreflink{image_alpha!} | \myreflink{image_cpt!} | \myreflink{imshow} | \myreflink{ind2rgb} |
+| \myreflink{info} | \myreflink{isnodata} | \myreflink{lelandshade} |
+| \myreflink{linearfitxy} | \myreflink{magic} | \myreflink{mat2ds} | \myreflink{mat2grid} | \myreflink{mat2img} | \myreflink{mosaic} | \myreflink{ODE2ds} | \myreflink{orbits} |
+| \myreflink{pca} | \myreflink{plotgrid!} | \myreflink{plotyy} \myreflink{pol2cart} | \myreflink{polygonlevels} | \myreflink{rasterzones!} | \myreflink{regiongeog} | \myreflink{rescale} |
+| \myreflink{slicecube} | \myreflink{sph2cart} | \myreflink{stackgrids} | \myreflink{ter2cart} | \myreflink{theme} | \myreflink{uniqueind} | \myreflink{vecangles} | \myreflink{weather} |
+| \myreflink{whereami} | \myreflink{wmsinfo} | \myreflink{wmsread} | \myreflink{wmstest} | \myreflink{worldrectgrid} | \myreflink{worldrectcoast} | \myreflink{worldrectangular} | \myreflink{xyzw2cube} |
+| \myreflink{yeardecimal} | \myreflink{zonal_stats} | | | | | | |
 
 
 ## GDAL utility functions

documentation/gdalfuns.txt

@@ -23,6 +23,8 @@ epsg2wkt
 equals
 envelope
 envelope3d
+fillnodata
+fillnodata!
 geod
 geodesic
 geomarea

documentation/general/types.md

@@ -24,10 +24,10 @@ type GMTgrid{T<:Real,N} <: AbstractArray{T,N} # The type holding a local he
  y::Array{Float64,1} # [1 x n_rows] vector with YY coordinates
  v::Union{Vector{<:Real}, Vector{String}} # [v x n_bands] vector with VV (vertical for 3D grids) coordinates
  z::Array{T,N} # [n_rows x n_columns] grid array
- x_units::String # Units of XX axis (Optional)
- y_units::String # Units of YY axis (Optional)
- v_units::String # Units of Vertical axis (Optional)
- z_units::String # Units of z vlues (Optional)
+ x_unit::String  # Units of XX axis (Optional)
+ y_unit::String  # Units of YY axis (Optional)
+ v_unit::String  # Units of Vertical axis (Optional)
+ z_unit::String  # Units of z vlues (Optional)
  layout::String # A three character string describing the grid memory layout
  scale::Union{Float64, Float32}=1f0 # When saving in file apply `z = z * scale + offset`
  offset::Union{Float64, Float32}=0f0

documentation/modules/colorbar.md

@@ -59,7 +59,7 @@ Optional Arguments
 
 \textinput{common_opts/opt_R}
 
-- **S** or **nolines** : -- *nolines=true*\
+- **S** or **nolines** or **appearance** : -- *nolines=true*\
  Do not separate different color intervals with black grid lines.
 
 \textinput{common_opts/opt_U}

documentation/modules/contour.md

@@ -33,7 +33,7 @@ Required Arguments
 Optional Arguments
 ------------------
 
-- **A** or **annot** : -- *annot=annot\_int* **|** *annot=(int=annot\_int, disable=true, single=true, labels=labelinfo)*\
+- **A** or **annot** or **annotation** : -- *annot=annot\_int* **|** *annot=(int=annot\_int, disable=true, single=true, labels=labelinfo)*\
  *annot\_int* is annotation interval in data units; it is ignored if contour levels are given in a file.
  [Default is no annotations]. Use *annot=(disable=true,)* to disable all annotations implied by **cont**.
  Alternatively do *annot=(single=true, int=val)* to plot *val* as a single contour. The optional *labelinfo* controls the specifics of the label formatting and consists of a named tuple with the following control arguments \myreflink{Label formatting}

documentation/modules/grdcontour.md

@@ -20,7 +20,7 @@ The 2-D gridded data set to be contoured.
 Optional Arguments
 ------------------
 
-- **A** or **annot** : -- *annot=annot\_int* **|** *annot=(int=annot\_int, disable=true, single=true, labels=labelinfo)*\
+- **A** or **annot** or **annotation** : -- *annot=annot\_int* **|** *annot=(int=annot\_int, disable=true, single=true, labels=labelinfo)*\
  *annot\_int* is annotation interval in data units; it is ignored if contour levels are given in a file.
  [Default is no annotations]. Use *annot=(disable=true,)* to disable all annotations implied by **cont**.
  Alternatively do *annot=(single=true, int=val)* to plot *val* as a single contour. The optional *labelinfo* controls the specifics of the label formatting and consists of a named tuple with the following control arguments \myreflink{Label formatting}

documentation/modules/image.md

@@ -59,7 +59,7 @@ Optional Arguments
 
 \textinput{common_opts/opt_box}
 
-- **G** or **bit_color** or **bit_bg|fg|alpha** : -- *bit_bg=color* **|** *bit_fg=color* **|** *bit_alpha=color* **|** *bit_color=color[+b|+f|+t]* \
+- **G** or **bitcolor** or **bit_color** or **bit_bg|fg|alpha** : -- *bit_bg=color* **|** *bit_fg=color* **|** *bit_alpha=color* **|** *bitcolor=color[+b|+f|+t]* \
  Change certain pixel values to another color or make them transparent. For 1-bit images you can
  specify an alternate *color* for the background (**bit_bg=color**) or the foreground (**bit_bf=color**)
  pixels, or give no color to make those pixels transparent. Alternatively, for color images you

documentation/modules/legend.md

@@ -62,7 +62,7 @@ Optional Arguments
 
 \textinput{common_opts/opt_J}
 
-- **M**\
+- **M** or **source** \
  Modern mode only: Read both (1) the hidden auto-generated legend information file created by plotting-modules'
  **legend** option (warning: **not** this **legend** module) and (2) additional information from input file(s)
  given on the command line [hidden file only].

documentation/utilities/cubeplot.md

@@ -1,7 +1,7 @@
 # cubeplot
 
 ```julia
-cubeplot(img1::Union{GMTimage, String}, img12::Union{GMTimage, String}="", img1e3::Union{GMTimage, String}="";
+cubeplot(img1::Union{GMTimage, String}, img2::Union{GMTimage, String}="", img3::Union{GMTimage, String}="";
  back::Bool=false, show=false, notop::Bool=false, kw...)
 ```
 
@@ -35,6 +35,85 @@ The `kw...` keyword/value options may be used to pass:
 
 - `transparency`: Sets the image's transparency level in the [0,1] or [0 100] intervals. Default is opaque.
 
+- `inset` or `hole`: Draws an inset hole in the cube's Southern wall. This option is a tuple with the form:
+ ``((img1,img2[,img3]), width=?, [depth=?])`` where ``(img1,img2[,img3])`` are the images of the `north`
+ (that is, the plane whose normal is `y`) and `west` (that is, the plane whose normal is `x`)
+ and, optionally, `bottom` sides of the inset. The `width` and `depth` are the width and depth of the inset.
+ If `depth` is not provided it defaults to `width`. These values **must** be given in percentage of the cube's width
+ and can be given in the [0-1] or [0-100] interval.
+
+- `xlabel, ylabel, zlabel, title`: Optional axes labels and title. Each one of these must be a string.
+
+- `cmap, colormap, cpt, colorscale`: Add a colorbar at the bottom of the figure. The colormap can be passed as a
+ single argument or as a tuple of arguments, where first must be the colormap and second [and optional a third]
+ are the axes colorbar labels taking the form: `cmap=(C, "xlabel=Blabla1"[, "ylabel=Blabla2"])`.
+
+---
+```julia
+cubeplot(G::GMTgrid; top=nothing, topshade=false, zdown::Bool=false, xlabel="", ylabel="", zlabel="", title="",
+ show=false, interp::Float64=0.0, kw...)
+```
+
+Make a 3D plot of a 3D GMTgrid (a cube) with a top view perspective from the 4rth quadrant (only one implemented).
+There are several options to control the painting of the cube walls but off course not all possibilities are covered.
+For ultimate control, users can create the side wall images separately and feed them to the cubeplot method that
+accepts only images as input. 
+
+- `cmap, colormap, cpt, colorscale`: Pass in a GMTcpt colormap to be used to paint the vertical walls and
+ optionally, the top wall. The default is to compute this from the cube's min/max values with the `turbo` colormap.
+
+- `colorbar`: Add a colorbar at the bottom of the figure. The plotted colormap is either the auto-generated colormap
+ (from the cube's min/max and the `turbo` colormap) or the one passed via the `cmap` option. The optional syntax of
+ this option is either: `colorbar=true` or `colorbar=(C, "xlabel=Blabla1"[, "ylabel=Blabla2"])`. Attention that when
+ the labels request are passed, thy MUST conform with the `xlabel=...` and `ylabel=...` prefix part.
+
+- `inset`: Add an inset to the figure. This inset takes the form of a _hole_ located in the lower right corner of
+ the cube in which its inner walls are painted with partial vertical slices of the cube. The `inset` option
+ may be passed as a two elements array or tuple where first element is the starting longitude (end is cube's easternmost
+ coordinate) and second the ending latitude (start is southernmost lat): an alternative syntax is to use
+ `inset=(lon=?, lat=?)`.
+
+- `interp`: When the cube layers are not equi-distant, the vertical side walls are not regular gris. This option,
+ that is called by default, takes care of obtaining a regular grid by linear interpolation along the columns.
+ This automatic interpolation uses the smallest increment in the vertical direction, but that may be overridden
+ by the `interp` increment option (a float value).
+
+- `region, limits`: A 4 elements array or Tuple (`x_min, x_max, y_min, y_max`) with the limits of a sub-region to display.
+ Default uses the entire cube.
+
+- `show`: If `true` display the figure. Default is `false`, _i.e._ it lets append further elements latter if wished.
+
+- `top`: An optional GMTgrid or the file name of a GMTgrid to be used to create the top wall of the cube. If, instead,
+ a GMTimage is passed we plot it directly (grids are converted to images using default colormaps or one passed via `topcmap`).
+ The default is to use the cube's first slice as the top wall.
+
+- `topshade`: Only used when the `top` option was used to pass a GMTgrid (or the name of one). When `true`, the top wall
+ image is created with the cube's first slice and a shaded effect computed with `grdgradient` on the `top` grid
+ (normally a topography grid). This creates a nice effect that shows both the cube's first layer and the topography where it lies. 
+ Optionally, the `topshade` option may be used with a `grdgradient` grid computed with any other grid.
+
+- `topcmap`: An alternative colormap for the top wall. Default is the same as the `turbo` computed with cube `G` itself.
+
+- `xlabel, ylabel, zlabel, title`: Optional axes labels and title. Each one of these must be a string.
+
+- `zdown`: When `true`, the z-axis is positive down. Default is `false` (positive up).
+
+- `zsize`: Vertical size of the plotted cube. Default is 6 cm. Use a negative value if the z-axis is positive down, but
+ see also the alternative `zdown` option.
+
+Example
+-------
+
+\begin{examplefig}{}
+```julia
+using GMT
+
+cubeplot(GMT.TESTSDIR * "seila_gray.jpg",
+ GMT.TESTSDIR * "seis_section_rgb.jpg",
+ GMT.TESTSDIR * "seis_section_gray.jpg",
+ zsize=6, show=true)
+```
+\end{examplefig}
 
 See Also
 --------

examples/misc/cube_sides.md

@@ -13,7 +13,7 @@ viz(GMT.peaks(N=100), zsize=8, facades=(GMT.TESTSDIR * "cenora_base.jpg",
 ```
 \end{examplefig}
 
-The above example used the helper function \myreflink{imshow} (well, it's alias ``viz``) that knew what to do when
+The above example used the helper function \myreflink{imshow} (well, its alias ``viz``) that knew what to do when
 it found the keyword `facades`, but in fact the work was done by the function \myreflink{cubeplot}. Next example shows
 how to call that function directly to plot three images in the front sides of the cube.
 

geophysics/seismicity/3D_vp_vs.md

@@ -0,0 +1,54 @@
+# 3D models with side walls
+
+These examples show a GMT.jl version of a PyGMT post in the GMT forum and that can be found at the original
+author's, JiahongLuo, Github site (https://github.com/Luojiahong/PyGMT_3D_mapview/blob/main/mapview_3d_earthquake.ipynb)
+
+The \myreflink{cubeplot} function let us easily plot images on the sides of a cube. That function can also be used
+to create those side figures directly from a 3D cube grid.
+
+```julia
+using GMT
+
+# Download data from:
+model = gmtread("https://github.com/ShouchengHan/USTClitho2.0/blob/main/USTClitho2.0.wrst.sea_level.txt");
+
+# Create two data cubes (grids) with the Vp and Vs velocities
+Cvp = xyzw2cube(model);
+Cvs = xyzw2cube(model, zcol=5);
+
+# Add names to the cube layers to be used as titles in next figure
+Cvp.names = ["Depth = $(Int(i)) km" for i in Cvp.v];
+Cvs.names = ["Depth = $(Int(i)) km" for i in Cvs.v];
+```
+
+Show all 12 layers of the P-waves velocity in a figure. We use a diffent colormap for each layer to avoid that
+layers become too monochromatic.
+
+\begin{examplefig}{}
+```julia
+using GMT # Hide
+viz(Cvp, colorbar=true, cmap=:same, title="Vp model")
+```
+\end{examplefig}
+
+Show the P and S velocities with a slight variation of the top layer. For the P-velocity we plot the topography on top
+and for the S-velocity we show the superficial S velocity but apply a shading effect calculated from the topography
+grid.
+
+\begin{examplefig}{}
+```julia
+using GMT # Hide
+cubeplot(Cvp, top="@earth_relief_05m", colorbar=("xlabel=P-wave velocity", "ylabel=km/s"), zdown=true, title="Vp model")
+cubeplot!(Cvs, top="@earth_relief_05m", topshade=true, zdown=true, colorbar=("xlabel=S-wave velocity", "ylabel=km/s"), xshift=18, title="Vs model", show=true)
+```
+\end{examplefig}
+
+To finish we show how to make an inset view in the 3D model.
+
+\begin{examplefig}{}
+```julia
+using GMT # Hide
+cubeplot(Cvp, top="@earth_relief", inset=(lon=100, lat=35), topshade=true, zdown=true,
+ colorbar=("xlabel=P-wave velocity", "ylabel=km/s"), show=true)
+```
+\end{examplefig}