WIP: DOC: Add Technical Reference page for reference and anchor points #4052
Conversation
yvonnefroehlich
added
the
documentation
|
|
||
| For placing plot embellishments, we distinguish between reference and anchor points. To set | ||
| these points users have to use the [justification codes](/techref/justification_codes.md). | ||
| The `offset` parameter allows to offset the anchor point from the reference point. |
There was a problem hiding this comment.
Please see changes in #4025. I think we should provide more details about the positioning of embellishments. The reference point is controlled by the position/position_type parameters, and the anchor point is defined by the anchor/anchor_offset parameters.
There was a problem hiding this comment.
Totally agree @seisman! Will wait and leave this PR as draft until you have finished the work on this.
There was a problem hiding this comment.
I think we should finish this PR first, so that we can reference this documentation in PRs like #4025.
There was a problem hiding this comment.
Ah OK, that's also fine with me. Hope I will have time to work on this PR in the next days.
There was a problem hiding this comment.
I continued working on this PR.
Now I am wondering about the timeline: introducing the parameters position, position_type, anchor, and anchor_offset is not only part of adding the high-level method Figure.directional_rose but this also affects other methods, e.g., Figure.colorbar and Figure.legend. This probably means before merging this PR, we have to adjust the codes of these methods.
There was a problem hiding this comment.
Yes, ideally these changes should be done in one release.
|
Bumping this PR to v0.18.0. |
Yeah, that's fine! Needed some time to work on cleaning up some codes and work on my own map repo 🙃. |
|
|
||
| # Reference and Anchor Points | ||
|
|
||
| For placing plot embellishments on a figure, we distinguish between two points: a point |
There was a problem hiding this comment.
Docstrings are pasted here:
position
Specify the reference point on the plot for the GMT logo. The method of defining
the reference point is controlled by ``position_type``, and the exact location
is set by ``position``.
position_type
Specify the type of coordinates used to define the reference point. It can be
one of the following values:
- ``"mapcoords"``: ``position`` is specified as (*longitude*, *latitude*) in map
coordinates. Example: (120, -45) places the reference point at 120°E, 45°S.
- ``"boxcoords"``: ``position`` is specified as (*nx*, *ny*) in normalized
coordinates, i.e., fractional values between 0 and 1 along the x- and y-axes.
Example: (0, 0) corresponds to the lower-left corner, and (1, 1) to the
upper-right corner of the plot bounding box.
- ``"plotcoords"``: ``position`` is specified as (*x*, *y*) in plot coordinates,
i.e., distances from the lower-left plot origin given in inches, centimeters,
or points. Example: ("1c", "2c") places the reference point 1 cm to the right
and 2 cm above the plot origin.
- ``"inside"`` or ``"outside"``: ``position`` is one of the nine
:doc:`two-character justification codes </techref/justification_codes>`,
indicating a specific location relative to the plot bounding box. Example:
``"TL"`` places the reference point at the top-left corner, either inside or
outside the bounding box.
anchor
Specify the anchor point of the GMT logo, using one of the
:doc:`2-character justification codes </techref/justification_codes>`.
The default value depends on ``position_type``.
- ``position_type="inside"``: ``anchor`` defaults to the same as ``position``.
- ``position_type="outside"``: ``anchor`` defaults to the mirror opposite of
``position``.
- Otherwise, ``anchor`` defaults to ``"MC"`` (middle center).
anchor_offset
Specifies an offset for the anchor point as *offset* or
(*offset_x*, *offset_y*). If a single value *offset* is given, both *offset_x*
and *offset_y* are set to *offset*.
Description of proposed changes
Add a Technical Reference page for reference and anchor points for plot embellishments.
Related to
DOC: Add Technical Reference page for justification codes #4028
Previews:
Reminders
make formatandmake checkto make sure the code follows the style guide.doc/api/index.rst.Slash Commands
You can write slash commands (
/command) in the first line of a comment to performspecific operations. Supported slash command is:
/format: automatically format and lint the code