Add standalone compass() function

src/GMT.jl

@@ -121,7 +121,7 @@ export
 	gmt_GMTgrid, libgdal, arrows, arrows!, bar, bar!, bar3, bar3!, band, band!, bubblechart, bubblechart!, crop,
 	feather, feather!, hband, hband!, hlines, hlines!, lines, lines!, legend, legend!, quiver, quiver!, radar,
 	radar!, stairs, stairs!, stem, stem!, vlines, vlines!, vband, vband!, hspan, hspan!, vspan, vspan!,
-	basemap, basemap!, blockmean, blockmedian, blockmode, clip, clip!,
+	basemap, basemap!, blockmean, blockmedian, blockmode, clip, clip!, compass, compass!,
 	coast, coast!, colorbar, colorbar!, colorscale, colorscale!, contour, contour!, contourf, contourf!, events,
 	filter1d, fitcircle, gmt2kml, gmtbinstats, binstats, gmtconnect, gmtconvert,
 	gmtinfo, gmtlogo, gmtlogo!, gmtmath, gmtregress, gmtread, gmtselect, gmtset, gmtsimplify, gmtspatial,
@@ -284,6 +284,7 @@ include("orbits.jl")
 include("plot.jl")
 include("project.jl")
 include("psbasemap.jl")
+include("compass.jl")
 include("psclip.jl")
 include("pscoast.jl")
 include("pscontour.jl")

src/compass.jl

@@ -0,0 +1,127 @@
+"""
+    compass(; kwargs...)
+
+Draw a map directional rose or magnetic compass on the map.
+
+If `dec` (magnetic declination) is provided, draws a magnetic compass rose (`-Tm`).
+Otherwise, draws a directional rose (`-Td`).
+
+Can be called standalone (creates its own plot) or as an overlay (`compass!`) on an existing plot.
+When called standalone without `region`/`proj`, a default canvas sized to fit the rose is created
+automatically.
+
+### Compass-specific options
+
+- **anchor** :: [Type => Tuple | Str] — Reference point on the map for the rose.
+- **width** :: [Type => Number | Str] — Width of the rose in cm.
+- **justify** :: [Type => Str] — Justification of the rose relative to anchor.
+- **labels** or **label** :: [Type => Str] — Comma-separated labels for the cardinal points.
+- **offset** :: [Type => Tuple | Str] — Offset from the anchor point.
+- **map** | **inside** | **outside** | **norm** | **paper** :: [Type => Str] — Coordinate system for the anchor.
+
+### Directional rose only (`-Td`)
+
+- **fancy** :: [Type => Bool | Int] — Draw a fancy rose. 1-3 for different levels.
+
+### Magnetic compass only (`-Tm`)
+
+- **dec** :: [Type => Number | Str] — Magnetic declination.
+- **rose_primary** :: [Type => Tuple | Str] — Pen for the primary rose circle.
+- **rose_secondary** :: [Type => Tuple | Str] — Pen for the secondary rose circle.
+- **annot** :: [Type => Tuple | Str] — Annotation info for the magnetic compass.
+
+All other keyword arguments (e.g., `region`, `proj`, `par`, `show`, `savefig`, `Vd`, etc.)
+are passed through to `basemap`.
+
+### Examples
+
+Draw a standalone directional rose:
+
+```julia
+compass(width=2.5, fancy=true, labels=",,,N", show=true)
+```
+
+Draw a directional rose as overlay:
+
+```julia
+coast(region=(-10,10,-10,10), proj=:Mercator, frame=:auto, land=:lightgray)
+compass!(width=2.5, anchor=(0,0), justify=:CM, fancy=true, labels=",,,N", show=true)
+```
+
+Draw a magnetic compass:
+
+```julia
+basemap(region=(-8,8,-6,6), proj=:Mercator, frame=:auto)
+compass!(anchor=(0,0), width=6, dec=-14.5, annot=(45,10,5,30,10,2),
+         rose_primary=(0.25,:blue), rose_secondary=0.5, labels="", show=true)
+```
+"""
+compass!(; kw...) = compass(; first=false, kw...)
+function compass(; first=true, kw...)
+	d = init_module(false, kw...)[1]		# Also checks if the user wants ONLY the HELP mode
+	compass(first, d)
+end
+function compass(first::Bool, d::Dict{Symbol, Any})
+
+	compass_keys = (:anchor, :width, :justify, :labels, :label, :offset,
+	                :map, :inside, :outside, :norm, :paper,
+	                :fancy, :dec, :rose_primary, :rose_secondary, :annot)
+
+	nt_pairs = Pair{Symbol,Any}[]
+	for k in compass_keys
+		haskey(d, k) && push!(nt_pairs, k => pop!(d, k))
+	end
+
+	is_magnetic = any(p -> p.first === :dec, nt_pairs)
+
+	# When standalone (first=true) and no region/proj given, create a paper-coordinates canvas.
+	has_RJ = any(k -> haskey(d, k), (:R, :region, :limits, :J, :proj, :projection))
+	if (first && !has_RJ)
+		# Get the width to size the canvas (default 5 cm)
+		w = 5.0
+		for p in nt_pairs
+			if p.first === :width
+				w = isa(p.second, Real) ? Float64(p.second) : 5.0
+				break
+			end
+		end
+		sz = ceil(w * 1.6; digits=1)	# Canvas slightly larger than the rose
+		d[:region] = (0, sz, 0, sz)
+		d[:proj] = "X$(sz)c"
+		# Default anchor to center of canvas in paper coordinates if not provided
+		has_anchor = any(p -> p.first === :anchor, nt_pairs)
+		has_coord  = any(p -> p.first in (:map, :inside, :outside, :norm, :paper), nt_pairs)
+		if !has_anchor && !has_coord
+			# No positioning at all — center the rose on the canvas
+			push!(nt_pairs, :paper => "$(sz/2)/$(sz/2)")
+			push!(nt_pairs, :justify => :CM)
+		elseif has_anchor && !has_coord
+			# User gave anchor but no coordinate system — use paper coords
+			anc = pop_anchor!(nt_pairs)
+			push!(nt_pairs, :paper => isa(anc, Tuple) ? join(anc, '/') : string(anc))
+		end
+	end
+
+	nt = (; nt_pairs...)
+
+	if is_magnetic
+		d[:compass] = nt    # -> parse_Tm -> -Tm
+	else
+		d[:rose] = nt       # -> parse_Td -> -Td
+	end
+
+	haskey(d, :frame) || haskey(d, :B) || (d[:frame] = :none)
+	helper_basemap(!first, true, d)
+end
+
+# Helper to pop :anchor from nt_pairs and return its value
+function pop_anchor!(pairs::Vector{Pair{Symbol,Any}})
+	for i in eachindex(pairs)
+		if pairs[i].first === :anchor
+			val = pairs[i].second
+			deleteat!(pairs, i)
+			return val
+		end
+	end
+	return nothing
+end

test/test_PSs.jl

@@ -33,6 +33,37 @@ r = basemap(region=("0.2t","0.35t",0,1), figsize=(-12,0.25), frame=(axes=:S, ann
 @test startswith(r, "psbasemap  -R0.2t/0.35t/0/1 -JX-12/0.25 -Bsa1H -Bpa15mf5m -BS --FORMAT_CLOCK_MAP=-hham")
 @test_throws ErrorException("slanted option: Only 'parallel' is allowed for the y-axis") basemap(yaxis=(slanted=:o,), Vd=dbg2)
 
+println("	COMPASS")
+# Standalone directional rose — auto canvas, auto center
+r = compass(width=3, fancy=true, Vd=dbg2);
+@test startswith(r, "psbasemap  -R0/4.9/0/4.9 -JX4.9c -Tdx2.45/2.45+w3+f+jCM")
+# Standalone with labels
+r = compass(width=2.5, fancy=2, labels=",,,N", Vd=dbg2);
+@test contains(r, "-Td") && contains(r, "+f2") && contains(r, "+l,,,N")
+# Standalone with anchor (auto paper coords)
+r = compass(width=3, anchor=(5,5), fancy=true, Vd=dbg2);
+@test contains(r, "-Tdx5/5+w3+f")
+# Standalone with explicit paper coord
+r = compass(width=3, paper="7/7", fancy=1, Vd=dbg2);
+@test contains(r, "-Tdx7/7+w3+f1")
+# Standalone with explicit R/J — no auto canvas
+r = compass(region=(-5,5,-5,5), proj=:merc, width=2.5, anchor=(0,0), fancy=3, Vd=dbg2);
+@test startswith(r, "psbasemap  -R-5/5/-5/5 -JM15c") && contains(r, "-Tdj0/0+w2.5+f3")
+# Magnetic compass — standalone
+r = compass(width=6, dec=-14.5, annot=(45,10,5,30,10,2), labels="", Vd=dbg2);
+@test contains(r, "-Tm") && contains(r, "+d-14.5") && contains(r, "+t45/10/5/30/10/2")
+# Magnetic compass with rose_primary/secondary
+r = compass(width=6, dec=-14.5, rose_primary=(0.25,:blue), rose_secondary=0.5, Vd=dbg2);
+@test contains(r, "+i0.25,blue") && contains(r, "+p0.5")
+# Overlay mode (compass!)
+basemap(region=(-10,10,-10,10), proj=:Mercator, frame=:auto, Vd=dbg2)
+r = compass!(width=2.5, anchor=(0,0), justify=:CM, fancy=true, labels=",,,N", Vd=dbg2);
+@test contains(r, " -R -J") || contains(r, "-R-10/10/-10/10 -J ")
+@test contains(r, "-Tdj0/0+w2.5+jCM+l,,,N+f")
+# frame=:none is default (no explicit frame draws no axes)
+r = compass(width=3, fancy=true, Vd=dbg2);
+@test !contains(r, "-B")
+
 println("	PSCLIP")
 d = [0.2 0.2; 0.2 0.8; 0.8 0.8; 0.8 0.2; 0.2 0.2];
 psclip(d, J="X3i", R="0/1/0/1", N=true, V=:q);