Let flatfv() deal with RGBA images. Either band or pixel interleaved. (#1588)

* Docstrings tweaks

* Add option 'logo' to 'pagebg'. Also add a under the hood -T option.

* Docstrings

* Let flatfv() deal with RGBA images. Either band or pixel interleaved.

Author: joa-quim

src/gdal_tools.jl

@@ -31,11 +31,12 @@ end
 
 Image/Grid reprojection and warping function.
 
-### Parameters
+### Args
 - `indata`:  Input data. It can be a file name, a GMTgrid or GMTimage object or a GDAL dataset
 - `options`: List of options. The accepted options are the ones of the gdal_translate utility.
             This list can be in the form of a vector of strings, or joined in a single string.
             The accepted options are the ones of the gdalwarp utility.
+
 - `kwargs`: Besides what was mentioned above one can also use `meta=metadata`, where `metadata`
             is a string vector with the form "NAME=...." for each of its elements. This data
             will be recognized by GDAL as Metadata.
@@ -54,14 +55,15 @@ end
 
 Fill selected raster regions by interpolation from the edges.
 
-### Parameters
+### Args
 - `data`:  Input data. It can be a file name, a GMTgrid or GMTimage object.
+
+### Kwargs
 - `nodata`: The nodata value that will be used to fill the regions. Otherwise use the `nodata` attribute of `indata`
    if it exists, or NaN if none of the above were set.
-- `kwargs`:
-  - band: the band number. Default is first layer in `indata` 
-  - maxdist: the maximum number of cels to search in all directions to find values to interpolate from. Default, fills all.
-  - nsmooth: the number of 3x3 smoothing filter passes to run (0 or more).
+- band: the band number. Default is first layer in `indata` 
+- maxdist: the maximum number of cels to search in all directions to find values to interpolate from. Default, fills all.
+- nsmooth: the number of 3x3 smoothing filter passes to run (0 or more).
 
 ### Returns
 The modified input `data`

src/psxy.jl

@@ -108,7 +108,7 @@ function common_plot_xyz(cmd0::String, arg1, caller::String, first::Bool, is3D::
 	cmd, = parse_common_opts(d, cmd, [:a :e :f :g :t :w :margin :params]; first=first)
 	cmd, opt_l = parse_l(d, cmd)		# Parse this one (legend) aside so we can use it in classic mode
 	cmd, opt_f = parse_f(d, cmd)		# Parse this one (-f) aside so we can check against D.attrib
-	cmd  = parse_these_opts(cmd, d, [[:D :shift :offset], [:I :intens], [:N :no_clip :noclip]])
+	cmd  = parse_these_opts(cmd, d, [[:D :shift :offset], [:I :intens], [:N :no_clip :noclip], [:T]])
 	parse_ls_code!(d::Dict)				# Check for linestyle codes (must be before the GMTsyntax_opt() call)
 	cmd  = GMTsyntax_opt(d, cmd)[1]		# See if an hardcore GMT syntax string has been passed by mk_styled_line!
 	(is_ternary) && (cmd = add_opt(d, cmd, "M", [:M :dump]))
@@ -591,13 +591,14 @@ end
 Check if using a background image to replace the page color.
 
 This function checks for the presence of a `pagebg` option that sets the page background image.
-Note that this different from the `background` or `bg` option that sets the plotting canvas background color.
+Note that this is different from the `background` or `bg` option that sets the plotting canvas background color.
 
 - `pagebg`: a NamedTuple with the following members
-	- `image`: the image name or a GMTimage/GMTgrid object
-	- `width`: the width of the background image in percentage of the page width (default: 0.8)
-	- `offset`: the offset of the background image in percentage of the page width (default: (0.0,0.0))
-	   If only one value is provided it is used for the X offset only.
+    - `image`: the image name or a GMTimage/GMTgrid object
+    - `logo`: To plot the GMT logo (from the global ``timestamp`` option) at the lower left corner.
+    - `width`: the width of the background image in percentage of the page width (default: 0.8)
+    - `offset`: the offset in paper units (cm prefrably) with respect to the center of the background
+       image (default: (0.0,0.0)). If only one value is provided it is used for the X offset only.
 
 OR 
 
@@ -607,6 +608,7 @@ OR
 function fish_pagebg(d::Dict, cmd::Vector{String}; autoJZ::Bool=true)::Vector{String}
 	((val = find_in_dict(d, [:pagebg])[1]) === nothing) && return cmd
 	width::Float64 = 0.8;	off_X::Float64 = 0.0;	off_Y::Float64 = 0.0	# The off's are offsets from the center
+	opt_U = ""
 	if isa(val, NamedTuple)
 		!haskey(val, :image) && error("pagebg: NamedTuple must contain the member 'image'")
 		fname = helper_fish_bgs(val[:image])		# Get the image name or set it under the hood if input is a GMTimage
@@ -617,6 +619,7 @@ function fish_pagebg(d::Dict, cmd::Vector{String}; autoJZ::Bool=true)::Vector{St
 			isa(off, Real) ? (off_X = off) : length(off) == 2 ? (off_X = off[1]; off_Y = off[2]) :
 				error("pagebg: offset must be a Real or a two elements Array/Tuple")
 		end
+		haskey(val, :logo) && (opt_U = " -U+o0+t")
 	else				# Here, val is just the file name or a GMTimage
 		fname = helper_fish_bgs(val)	# Get the image name or set it under the hood if input is a GMTimage
 	end
@@ -647,7 +650,7 @@ function fish_pagebg(d::Dict, cmd::Vector{String}; autoJZ::Bool=true)::Vector{St
 		cmd[ind_cmd] = replace(cmd[ind_cmd], opt_JZ => CTRL.pocket_J[3])
 	end
 	proggy = IamModern[1] ? "image " : "psimage "
-	[proggy * fname * CTRL.pocket_J[1] * CTRL.pocket_R[1] * " -Dx0/0+w"*Wt*cw, cmd...]
+	[proggy * fname * CTRL.pocket_J[1] * CTRL.pocket_R[1] * opt_U * " -Dx0/0+w"*Wt*cw, cmd...]
 end
 
 # ---------------------------------------------------------------------------------------------------

src/solids.jl

@@ -683,10 +683,13 @@ end
 """
     FV = flatfv(I::Union{GMTimage, AbstractString}; shape=nothing, level=0.0) ->GMTfv
 
-Create a flat 3D surface from an image and a set of xyz or just xy coordinates.
+Create a flat 3D surface from an image and a set of xyz or xy coordinates.
 
-This function creates face for each pixel in the image that is inside the `shape` and assigns the
-face's color from that of the image. So be careful that the image is not too large.
+This function creates a face for each pixel in the image that is inside the `shape` and assigns the
+face's color from that of the image. So be careful that the image is not too large. As explained below,
+this function creates flat surfaces in any of the xy, xz or yz planes. While this may seam a big
+limitation, it can be circumvented by a posterior rotation of the image with the help of a rotation
+matrix created with the `eulermat` function.
 
 ### Args
 - `I`: A `GMTimage` object or a file name of an image.
@@ -717,7 +720,16 @@ function flatfv(I::Union{GMTimage, AbstractString}; shape=:n, level=0.0)::GMTfv
 	end
 
 	_I = forceRGB(I)
-	n_rows::Int, n_cols::Int = size(_I.image)
+	n_cols::Int, n_rows::Int = getsize(_I)	# Works for both 'regular' and GDAL transposed images
+
+	hasAlphaMask = (length(_I.layout) == 4 && _I.layout[4] == 'A')
+	if hasAlphaMask
+		if (_I.layout[3] == 'B')				# Band interleaved
+			_masca = (_I.image[:, :, 4] .== 255)'
+		else									# Pixel interleaved
+			_masca = reshape((_I.image[4:4:end] .== 255), n_cols, n_rows)'
+		end
+	end
 
 	if (shape == :circle || shape == :circ || shape == :ellipse)
 		X,Y = meshgrid(linspace(0, 1, n_cols+1), linspace(1, 0, n_rows+1))
@@ -754,15 +766,30 @@ function flatfv(I::Union{GMTimage, AbstractString}; shape=:n, level=0.0)::GMTfv
 	end
 	doMask = !isempty(masca)
 
+	if (hasAlphaMask)
+		masca = doMask ? masca .& _masca : _masca
+		doMask = true
+	end
+
 	FV = surf2fv(X, Y, Z, type=:quad, mask=masca)
 	n_colors = doMask ? sum(masca) : (n_rows * n_cols)
 	cor = Vector{String}(undef, n_colors)
 
 	kk = 0
-	@inbounds for n = 1:n_cols, m = 1:n_rows
-		doMask && !masca[m,n] && continue
-		k = (m-1) * n_cols * 3 + (n-1) * 3
-		cor[kk+=1] = @sprintf("-G#%.2x%.2x%.2x", _I[k+=1], _I[k+=1], _I[k+=1])
+	if (_I.layout[3] == 'P')		# Pixel interleaved
+		n_interleaved = (length(_I.layout) == 4 && _I.layout[4] == 'A') ? 4 : 3
+		@inbounds for n = 1:n_cols, m = 1:n_rows
+			doMask && !masca[m,n] && continue
+			k = (m-1) * n_cols * n_interleaved + (n-1) * n_interleaved
+			cor[kk+=1] = @sprintf("-G#%.2x%.2x%.2x", _I[k+=1], _I[k+=1], _I[k+=1])
+		end
+	else							# Band interleaved
+		nxy, nxy2 = n_rows * n_cols, n_rows * n_cols * 2
+		@inbounds for n = 1:n_cols, m = 1:n_rows
+			doMask && !masca[m,n] && continue
+			k = (m-1) * n_cols + n
+			cor[kk+=1] = @sprintf("-G#%.2x%.2x%.2x", _I[k], _I[k+nxy], _I[k+nxy2])
+		end
 	end
 
 	FV.color, FV.isflat = [cor], true

src/utils.jl

@@ -987,8 +987,10 @@ getbb(D::GDtype) = isa(D, Vector) ? D[1].ds_bbox : D.ds_bbox
 """
     width, height = getsize(GI::GItype) -> Tuple(Int, Int)
 
-Return the width and height of the grid or image. The grid case is simple but images are more complicated
-due to the memory layout. To disambiguate this, we are not relying in 'size(GI)' but on the length of the
+Return the width and height of the grid or image.
+
+The grid case is simple but images are more complicated due to the memory layout.
+To disambiguate this, we are not relying in 'size(GI)' but on the length of the
 x,y coordinates vectors, that are assumed to always be correct. 
 """
 function getsize(GI::GItype)
@@ -1039,8 +1041,9 @@ end
 """
     settimecol!(D::GDtype, Tcol)
 
-Set the time column in the dataset D (or vector of them). `Tcol` is either an Int scalar or vector
-of Ints with the column number(s) that hold the time columns.
+Set the time column in the dataset D (or vector of them).
+
+`Tcol` is either an Int scalar or vector of Ints with the column number(s) that hold the time columns.
 """
 settimecol!(D::GDtype, Tc::Int) = isa(D, Vector) ? (D[1].attrib["Timecol"] = string(Tc)) : (D.attrib["Timecol"] = string(Tc))
 settimecol!(D::GDtype, Tc::VecOrMat{<:Int}) = isa(D, Vector) ? (D[1].attrib["Timecol"] = join(Tc, ",")) : (D.attrib["Timecol"] = join(Tc, ","))
@@ -1052,10 +1055,13 @@ const set_timecol! = settimecol!
 
 Changes the geometry of the dataset `D` (or vector of them). The keyword version takes precedence.
 
-### Parameters
+### Args
 - `D`: A GMTdataset, or a vector of them.
 - `geom` | `gm`: the new geometry to apply to D. These are alternatives ways of seting the geometry
   but the keyword version takes precedence.
+
+### Kwargs
+- `geom`: the new geometry to apply to D.
 """
 function setgeom!(D::GMTdataset, gm::Integer=0; geom::Integer=0)
 	D.geom = (geom != 0) ? geom : gm	# The keyword version takes precedenceg
@@ -1067,11 +1073,13 @@ end
 
 # ---------------------------------------------------------------------------------------------------
 """
-    refsystem_A2B!(A, B)
+    refsystem_A2B!(A, B) -> nothing
+
+Copy the referencing information in object `A` to object `B`.
 
-Copy the referencing information in object `A` to object `B`. Both `A` and `B` can be either a GMTgrid or
-GMTimage or GMTdataset or vectors of GMTdataset objects. Attention that any previous referencing information
-stored in object `A` will be lost (replaced by that on object `B`).
+Both `A` and `B` can be either a GMTgrid or GMTimage or GMTdataset or vectors of GMTdataset objects.
+Attention that any previous referencing information stored in object `A` will be lost
+(replaced by that on object `B`).
 """
 function refsystem_A2B!(A, B)
 	prj, wkt, epsg = isa(A, Vector) ? (A[1].proj4, A[1].wkt, A[1].epsg) : (A.proj4, A.wkt, A.epsg)
@@ -1118,7 +1126,7 @@ end
 """
     overlap, value = rect_overlap(xc_1, yc_1, xc_2, yc_2, width1, height1, width2, height2) -> Bool, Float64
 
-Check if two rectangles, aligned with the axes, overlap.
+Check if two rectangles, aligned with the axes (non-rotated), overlap.
 
 - `xc_1, yc_1`: Center of the first rectangle
 - `xc_2, yc_2`: Center of the second rectangle