Add a 'pagebg' option that lets users paint the background paper with an image. (#1587)

* Add tests

* Export flatfv

* Let 'opt' in scan_opt() have more than 2 chars.

* Move a developing function to elsewhere.

* Add a maskregion() function.

* Add a flatfv() function (renamed from imgfv)

* Add a 'pagebg' option that lets users paint the background paper with an image.

Author: joa-quim

src/GMT.jl

@@ -15,6 +15,7 @@ struct CTRLstruct
 	pocket_call::Vector{Any}		# To temporarily store data needed by modules sub-calls. Put in [3] for pre-calls
 	pocket_B::Vector{String}		# To temporarily store opt_B grid and fill color to be reworked in psclip
 	pocket_J::Vector{String}		# To temporarily store opt_J and fig size to eventualy flip directions (y + down, etc)
+									# = [opt_J width opt_Jz codes-to-tell-which-axis-to-reverse]
 	pocket_R::Vector{String}		# To temporarily store opt_R
 	XYlabels::Vector{String}		# To temporarily store the x,y col names to let x|y labels know what to plot (if "auto")
 	IamInPaperMode::Vector{Bool}	# A 2 elem vec to know if we are in under-the-hood paper mode. 2nd traces if first call
@@ -185,8 +186,8 @@ export
 
 	lazinfo, lazread, lazwrite, lasread, laswrite,
 
-	cube, cylinder, circlepts, dodecahedron, ellipse3D, eulermat, icosahedron, loft, sphere, spinmat, octahedron,
-	tetrahedron, torus, replicant, revolve, rotate, rotate!, translate, translate!,
+	cube, cylinder, circlepts, dodecahedron, ellipse3D, eulermat, flatfv, icosahedron, loft, sphere, spinmat,
+	octahedron, tetrahedron, torus, replicant, revolve, rotate, rotate!, translate, translate!,
 
 	df2ds, ds2df, extrude, fv2fv, isclockwise, surf2fv, ODE2ds,
 	@?, @dir

src/common_options.jl

@@ -4972,16 +4972,22 @@ end
 """
     str = scan_opt(cmd::AbstractString, opt::String, keepX=false)
 
-Scans the CMD string for the OPT option. Note, OPT must be a 2 chars -X GMT option.
+Scans the CMD string for the OPT option. Note, OPT must be at least a 2 chars -X GMT option.
 'keepX' retains the OPT 2 chars -X GMT option in output.
 
 ### Example
+```julia
     scan_opt(" -Baf", "-B", true)
 	" -Baf"
+
+	scan_opt(" -R -JX -JZ4", "-JZ")
+    "4"
+```
 """
 function scan_opt(cmd::AbstractString, opt::String, keepX::Bool=false)::String
-	out::String = ((ind = findfirst(opt, cmd)) !== nothing) ? (ind[end] == length(cmd)) ? "" : strtok(cmd[ind[1]+2:end])[1] : ""
-	(out != "" && cmd[ind[1]+2] == ' ') && (out = "")		# Because seeking -R in a " -R -JX" would ret "-JX"
+	len = length(opt)
+	out::String = ((ind = findfirst(opt, cmd)) !== nothing) ? (ind[end] == length(cmd)) ? "" : strtok(cmd[ind[1]+len:end])[1] : ""
+	(out != "" && cmd[ind[1]+len] == ' ') && (out = "")		# Because seeking -R in a " -R -JX" would ret "-JX"
 	(keepX && out != "") && (out = string(' ', opt, out))	# Keep the option flag in output
 	return out
 end

src/psxy.jl

@@ -158,8 +158,8 @@ function common_plot_xyz(cmd0::String, arg1, caller::String, first::Bool, is3D::
 		cmd = replace(cmd, opt_J => " -JX" * split(DEF_FIG_SIZE, '/')[1] * "/0")	# If projected, it's a axis equal for sure
 	end
 	if (is3D && isempty(opt_JZ) && length(collect(eachmatch(r"/", opt_R))) == 5)
-		if O  opt_JZ = (CTRL.pocket_J[3] != "") ? CTRL.pocket_J[3][1:4] : " -JZ"
-		else  opt_JZ = CTRL.pocket_J[3] = (is_gridtri) ? " -JZ5c" : " -JZ6c"		# Arbitrary and not satisfactory for all cases.
+		if (O) opt_JZ = (CTRL.pocket_J[3] != "") ? CTRL.pocket_J[3][1:4] : " -JZ"
+		else   opt_JZ = CTRL.pocket_J[3] = (is_gridtri) ? " -JZ5c" : " -JZ6c"		# Arbitrary and not satisfactory for all cases.
 		end
 		cmd *= opt_JZ		# Default -JZ
 	end
@@ -339,6 +339,7 @@ function common_plot_xyz(cmd0::String, arg1, caller::String, first::Bool, is3D::
 	end
 
 	_cmd = fish_bg(d, _cmd)					# See if we have a "pre-command"
+	_cmd = fish_pagebg(d, _cmd, autoJZ=(is3D && axis_equal))	# Last arg tells if JZ was computed automatically
 
 	isa(arg1, GDtype) && plt_txt_attrib!(arg1, d, _cmd)			# Function barrier to plot TEXT attributed labels (in case)
 
@@ -584,23 +585,111 @@ function with_xyvar(d::Dict, arg1::GMTdataset, no_x::Bool=false)::Union{GMTdatas
 end
 
 # ---------------------------------------------------------------------------------------------------
+"""
+    cmd = fish_pagebg(d::Dict, cmd::Vector{String}) -> Vector{String}
+
+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.
+
+- `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.
+
+OR 
+
+- `pagebg`: an image file name or a GMTimage/GMTgrid object
+   In this case the above defaults for the _width_ and _offset_ parameters are used
+"""
+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
+	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
+		haskey(val, :width) && (width = val[:width])
+		(width <= 0 || width > 1) && error("pagebg: width is a normalized value, must be between 0 and 1")
+		if (haskey(val, :offset) || haskey(val, :off))
+			off = (haskey(val, :offset)) ? val[:offset] : val[:off]
+			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
+	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
+
+	if contains(CTRL.pocket_J[2], "/")  Wt, Ht = split(CTRL.pocket_J[2], '/')
+	else                                Wt = CTRL.pocket_J[2]; Ht = "/0"
+	end
+	isletter(Wt[end]) ? (cw=Wt[end]; Wt = Wt[1:end-1]) : (cw = 'c')
+	isletter(Ht[end]) ? (ch=Ht[end]; Ht = Ht[1:end-1]) : (ch = 'c');	(Ht == "0") && (Ht = "/0")
+	W = parse(Float64, Wt)
+	if (Ht != "" && Ht != "/0")			# User gave an explicit height
+		H = parse(Float64, Ht) * width	# r = H / W; H = r * width * W; = H * width
+		Ht = @sprintf("/%.4g%c", H, ch)
+	end
+
+	off_XY = @sprintf(" -X%.4g%c", off_X + (1-width)/2 * W, cw)
+	(off_Y != 0.0) && (off_XY *= @sprintf(" -Y%.4g%c", off_Y, cw))
+	opt_J = scan_opt(cmd[1], "-J", true)
+	new_J = string(opt_J[1:4], width * W, cw, Ht)
+
+	# If the 'bg' option is also set it sits in cmd[1] and then we want to modify cmd[2].
+	ind_cmd = startswith(cmd[1], "grdimage") ? 2 : 1	# The presence of 'grdimage' says that 'bg' was used.
+
+	cmd[ind_cmd] = replace(cmd[ind_cmd], opt_J => new_J * off_XY)
+	if (autoJZ && (opt_JZ = scan_opt(cmd[1], "-JZ", true)) != "")	# Only do this for JZ that was set automatically
+		z = parse(Float64, isletter(opt_JZ[end]) ? opt_JZ[5:end-1] : opt_JZ[5:end]) * width
+		CTRL.pocket_J[3] = @sprintf(" -JZ%.4g%c", z, cw)
+		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...]
+end
+
+# ---------------------------------------------------------------------------------------------------
+"""
+    cmd = fish_bg(d::Dict, cmd::Vector{String}) -> Vector{String}
+
+Check if a background image in a plot area is requested.
+
+Check if the background image is used and if yes insert a first command that calls grdimage to fill
+the canvas with that bg image. The BG image can be a file name, the name of one of the pre-defined
+functions, or a GMTgrid/GMTimage object. By default we use a trimmed gray scale (between ~64 & 240)
+but if user wants to control the colormap then the option's argument can be a tuple where the second
+element is cpt name or a GMTcpt obj.
+
+### Example
+
+```julia
+plot(rand(8,2), bg=(:somb, :turbo), show=1)
+
+# To revert the sense of the color progression prefix the cpt name or of the pre-def function with a '-'
+
+plot(rand(8,2), bg="-circ", show=1)
+```
+"""
 function fish_bg(d::Dict, cmd::Vector{String})::Vector{String}
-	# Check if the background image is used and if yes insert a first command that calls grdimage to fill
-	# the canvas with that bg image. The BG image can be a file name, the name of one of the pre-defined
-	# functions, or a GMTgrid/GMTimage object.
-	# By default we use a trimmed gray scale (between ~64 & 240) but if user wants to control the colormap
-	# then the option's argument can be a tuple where the second element is cpt name or a GMTcpt obj.
-	# Ex:  plot(rand(8,2), bg=(:somb, :turbo), show=1)
-	# To revert the sense of the color progression prefix the cpt name or of the pre-def function with a '-'
-	# Ex: plot(rand(8,2), bg="-circ", show=1)
 	((val = find_in_dict(d, [:bg :background])[1]) === nothing) && return cmd
+	fname = helper_fish_bgs(val)
+
+	opt_p = scan_opt(cmd[1], "-p", true);		opt_c = scan_opt(cmd[1], "-c", true)
+	opt_D = (IamModern[1]) ? " -Dr " : " -D "	# Found this difference by experience. It might break in future GMTs
+	["grdimage" * opt_D * fname * CTRL.pocket_J[1] * opt_p * opt_c, cmd...]
+end
+
+function helper_fish_bgs(val)::String
 	arg1, arg2 = isa(val, Tuple) ? val[:] : (val, nothing)
-	(arg2 !== nothing && (!isa(arg2, GMTcpt) && !isa(arg2, StrSymb))) &&error("When a Tuple is used in argument of the background image option, the second element must be a string or a GMTcpt object.")
+	(arg2 !== nothing && (!isa(arg2, GMTcpt) && !isa(arg2, StrSymb))) &&
+		error("When a Tuple is used in argument of the background image option, the second element must be a string or a GMTcpt object.")
 	gotfname, fname::String, opt_I::String = false, "", ""
 	if (isa(arg1, StrSymb))
-		if (splitext(string(arg1)::String)[2] != "")		# Assumed to be an image file name
+		if (splitext(string(arg1)::String)[2] != "")	# Assumed to be an image file name
 			fname, gotfname = arg1, true
-		else										# A pre-set fun name
+		else											# A pre-set fun name
 			fun::String = string(arg1)
 			(fun[1] == '-') && (fun = fun[2:end]; opt_I = " -I")
 			I::GMTimage = imagesc(mat2grid(fun))
@@ -617,12 +706,8 @@ function fish_bg(d::Dict, cmd::Vector{String})::Vector{String}
 		image_cpt!(I, C)
 		CTRL.pocket_call[3] = I					# This signals finish_PS_module() to run _cmd first
 	end
-
-	opt_p = scan_opt(cmd[1], "-p");		(opt_p != "") && (opt_p = " -p" * opt_p)
-	opt_c = scan_opt(cmd[1], "-c");		(opt_c != "") && (opt_c = " -c" * opt_c)
-	#(opt_c == "" && contains(cmd[1], " -c ")) && (opt_c = " -c")	# Because of a scan_opt() desing error (but causes error)
-	opt_D = (IamModern[1]) ? " -Dr " : " -D "	# Found this difference by experience. It might break in future GMTs
-	["grdimage" * opt_D * fname * CTRL.pocket_J[1] * opt_p * opt_c, cmd...]
+	FIG_MARGIN[1] = 0
+	return fname
 end
 
 # ---------------------------------------------------------------------------------------------------

src/rasterpolygonfuns.jl

@@ -293,3 +293,23 @@ function meansqrt(x)
 	end
 	sqrt(sum/length(x))
 end
+
+# ---------------------------------------------------------------------------------------------------
+"""
+    mask = maskregion(X::Matrix{T}, Y::Matrix{T}, shape) where {T <: AbstractFloat}
+"""
+function maskregion(X::Matrix{T}, Y::Matrix{T}, shape) where {T <: AbstractFloat}
+	# Need to add more methods and documentation
+	@assert length(X) == length(Y) "X and Y matrices have different sizes"
+	masca = BitArray(undef,size(X).-1)
+	n_rows, n_cols = size(masca)
+	# A a bug in 'pip'. pip(-0.5011, -3.469446951953614e-17, shape) = -1 but  pip(-0.5011, 0, shape) = 1
+	dx = (X[1,2]-X[1,1]) / 2.0
+	dy = (Y[2,1]-Y[1,1]) / 2.0
+	Threads.@threads for col = 1:n_cols
+		for row = 1:n_rows
+			@inbounds masca[row,col] = pip(X[row,col]+dx, Y[row,col]+dy, shape) >= 0
+		end
+	end
+	return masca
+end

src/solids.jl

@@ -677,3 +677,94 @@ function loft(C1, C2; n_steps::Int=0, closed=true, type=:quad)
 
 	surf2fv(X, Y, Z; type=type, bfculling=(closed != 1), top=top, bottom=bot)
 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.
+
+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.
+
+### Args
+- `I`: A `GMTimage` object or a file name of an image.
+
+### Kwargs
+- `shape`: A xyz or xy polygon defining a flat surface. When it is a 3D polygon, it must lie in the xz or yz planes.
+   But it can also be a can also be a Symbol; one of `:circle`, `:circ`, `:ellipse`. In this later case, we
+   compute a normalized circle or ellipse with dimensions taken from number of rows and columns in `I`.
+   The ellipse (with a horizontal major) eccentricity  is computed from the ratio of the number of rows and columns.
+- `level`: In case that `shape` is a polygon in the xy plane, this is the level or height of that flat surface.
+   For other plane orientations, this level is extracted from the column of constant values in `shape`.
+
+Returns:
+- A `GMTfv` object representing the flat 3D surface.
+
+### Example
+```julia
+FV = flatfv("image.png", shape=:circle, level=1.0);
+viz(FV)
+```
+"""
+function flatfv(I::Union{GMTimage, AbstractString}; shape=:n, level=0.0)::GMTfv
+
+	function forceRGB(I)::GMTimage{UInt8, 3}
+		I_ = isa(I, GMTimage) ? I : gmtread(I)::GMTimage
+		size(I_, 3) == 1 && (I_ = ind2rgb(I_))
+		return I_
+	end
+
+	_I = forceRGB(I)
+	n_rows::Int, n_cols::Int = size(_I.image)
+
+	if (shape == :circle || shape == :circ || shape == :ellipse)
+		X,Y = meshgrid(linspace(0, 1, n_cols+1), linspace(1, 0, n_rows+1))
+		Z = fill(Float64(level), n_rows+1, n_cols+1)
+		if (shape == :ellipse)
+			e = sqrt(1 - ((n_rows+1) / (n_cols+1))^2)
+			masca = maskregion(X, Y, ellipse3D(0.5; center=(0.5, 0.5), e=e))	# An horizontal ellipse
+		else
+			masca = maskregion(X, Y, circlepts(0.5; center=(0.5, 0.5)))			# A normalized circle
+		end
+	elseif (isa(shape, Array{<:AbstractFloat}))
+		if (size(shape, 2) == 2)
+			xc = extrema(view(shape, :, 1))			# Start and end coordinates
+			yc = extrema(view(shape, :, 2))
+			X,Y = meshgrid(linspace(xc[1], xc[2], n_cols+1), linspace(yc[2], yc[1], n_rows+1))
+			Z = fill(Float64(level), n_rows+1, n_cols+1)
+			masca = maskregion(X, Y, shape)
+		elseif (size(shape, 2) == 3)				# A cicle but not necessarily in the xy plane
+			c0 = std(diff(view(shape, :, 1), dims=1)) ≈ 0 ? 1 : std(diff(view(shape, :, 2), dims=1)) ≈ 0 ? 2 :
+			     std(diff(view(shape, :, 3), dims=1)) ≈ 0 ? 3 : error("'shape' is not a circle in the horizontal or vertical planes.")
+			two_col = (c0 == 1) ? (2,3) : (c0 == 2) ? (1,3) : (1,2)		# The indices of the non-zero columns
+			xc = extrema(view(shape, :, two_col[1]))
+			yc = extrema(view(shape, :, two_col[2]))
+			_X,_Y = meshgrid(linspace(xc[1], xc[2], n_cols+1), linspace(yc[2], yc[1], n_rows+1))
+			masca = maskregion(_X, _Y, shape[:, [two_col[1], two_col[2]]])
+			level = (c0 == 1) ? shape[1] : (c0 == 2) ? shape[1,2] : shape[1,3]
+			_Z = fill(Float64(level), n_rows+1, n_cols+1)
+			X, Y, Z = (c0 == 1) ? (_Z, _X, _Y) : (c0 == 2) ? (_X, _Z, _Y) : (_X, _Y, _Z)
+		end
+	else
+		X,Y = meshgrid(_I.x, reverse(_I.y))		# MUST CONFIRM that these coords are pixel-reg
+		Z = fill(Float64(level), n_rows+1, n_cols+1)
+		masca = BitArray(undef,0,0)
+	end
+	doMask = !isempty(masca)
+
+	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])
+	end
+
+	FV.color, FV.isflat = [cor], true
+	return FV
+end