WIP: DOC: Add Technical Reference page for reference and anchor points

doc/techref/index.md

@@ -14,5 +14,6 @@ fonts.md
 text_formatting.md
 encodings.md
 justification_codes.md
+reference_anchor_points.md
 environment_variables.md
 ```

doc/techref/justification_codes.md

@@ -5,10 +5,11 @@ file_format: mystnb
 # Justification Codes
 
 To place plot embellishments, such as scalebars, directional roses, colorbars, legends,
-text, or images on a figure, two points have to be specified: a point somewhere on the
-figure (**reference point**) and a point on the feature (**anchor point**). For both,
-users can use a two-character code, a combination of a vertical code and a horizontal
-code (order-independent):
+text, or images on a figure, two points have to be specified a point somewhere on the
+figure (**reference point**) and a point on the feature (**anchor point**); for details
+please see [Reference and anchor points](/techref/reference_anchor_points.md). For both,
+users can use a two-character code, a combination of a vertical code and a horizontal code
+(order-independent):
 
 - Vertical: **T**(op), **M**(iddle), **B**(ottom)
 - Horizontal: **L**(eft), **C**(entre), **R**(ight)

doc/techref/reference_anchor_points.md

@@ -0,0 +1,67 @@
+---
+file_format: mystnb
+---
+
+# Reference and Anchor Points
+
+For placing plot embellishments on a figure, we distinguish between two points: a point
+somewhere on the figure (**reference point**) and a point on the feature (**anchor point**).
+Four parameters are used to set and adjust these two points:
+
+- `position`: a point somewhere on the figure corresponding to `position_type`.
+- `position_type`: how to specify `position`. Choose between
+   - ``"inside"`` / ``"outside"``: inside / outside the plot bounding box using the [justification codes](/techref/reference_anchor_points.md),
+   - ``"mapcoords"``: map coordinates,
+   - ``"plotcoords"``: plot coordinates optionally with a unit,
+   - ``"boxcoords"``: normalized (0-1) coordinates corresponding to the bounding box.
+
+- `anchor`: a point on the feature specified using the [justification codes](/techref/justification_codes.md).
+- `anchor_offset`: offset the anchor point by *dx* and *dy* from the reference point.
+
+
+
+```{code-cell}
+---
+tags: [remove-input]
+---
+"""
+Script explaining reference and anchor points.
+"""
+import pygmt
+
+size = 5
+x1 = [-size, 0, size, size, size, 0, -size, -size, 0]
+y1 = [-size, -size, -size, 0, size, size, size, 0, 0]
+x2 = [-3, -2, -1, -1, -1, -2, -3, -3, -2]
+y2 = [-1, -1, -1, 0, 1, 1, 1, 0, 0]
+codes = ["BL", "BC", "BR", "MR", "TR", "TC", "TL", "ML", "MC"]
+
+fig = pygmt.Figure()
+fig.basemap(projection="X10c/6c", region=[-size, size, -size, size], frame=0)
+
+fig.text(
+    text=codes,
+    x=x1,
+    y=y1,
+    justify=codes,
+    offset="j0.5c/0.2c+v1p,gray30",
+    font="10p,1,black",
+)
+
+fig.plot(x=x2[0:-1], y=y2[0:-1], fill="bisque")
+
+fig.plot(x=-size, y=size, style="s0.6c", fill="lightred", no_clip=True)
+fig.plot(x=x1, y=y1, style="c0.25c", fill="steelblue", no_clip=True)
+
+fig.plot(x=-3, y=1, style="s0.6c", fill="orange")
+fig.plot(x=x2, y=y2, style="c0.15c", fill="darkblue")
+
+fig.plot(x=[-5, -3], y=[5, 1], pen="0.5p,black")
+fig.plot(x=[-5, -3], y=[1, 1], pen="0.5p,black,2_2")
+fig.plot(x=[-3, -3], y=[1, 5], pen="0.5p,black,2_2")
+
+fig.text(x=-4, y=1, text="dx", offset="0c/0.2c")
+fig.text(x=-3, y=3, text="dy", offset="-0.2c/0c")
+
+fig.show(width=600)
+```