Figures & Images

Figure 1: An example figure.

.. prefix: shfigs

.. _icgsphinxhelp-figures:

Figures & Images
#############################

.. figure:: /flac3d/zone/test3d/ExampleApplications/CavityExpansion/cavity-model.png
   :width: 85%
   :name: shfigs-top

   An example figure.

Output plots from codes represent the majority of figure use in ICG docs. The above example illustrates good usage. It breaks down as follows.

.. figure:: directive

The figure is inserted in the document with the .. figure:: directive, which is immediately followed by the location of the needed image file. Use either a complete path or a downward relative path, please (and don’t use an upward relative path).

Please Don’t

Please do not include an :align: center option in figures. This is outdated usage; figures are centered by default.

:width: option

Width is set as a percentage of the host column width. Code plots should uniformly use 85%. Other figures will need greater or lower values, or none at all if the native size of the image is already smaller than the column width (in which case, omit the :width option).

:name: option

Use this option to set the anchor for the figure. Note how the example above makes use of the document prefix.

caption

The caption for a figure follows. Always use periods (.) in captions, even if the caption is not a complete sentence.

Linking by Figure Number

Figure numbering seen in the caption is performed automatically. To refer to a figure by that number, instead of using the “standard” :ref: role (e.g., to the figure above), use the :fnum: role (e.g., see Figure 1 above).

Linking by Figure Number
++++++++++++++++++++++++

Figure numbering seen in the caption is performed automatically. To refer
to a figure by that number, instead of using the "standard" ``:ref:`` role
(e.g., to the :ref:`figure above <shfigs-top>`), use the ``:fnum:`` role
(e.g., see :fnum:`Figure #shfigs-top` above).

This bit of automagic is handled by an extension named numfig. What documentation exists for the extension is at https://sourceforge.net/p/numfig/wiki/Home/ .

Images

Usage for the .. image:: directive is the same as for a .. figure:: — the difference between the two being that .. image:: does not take a caption. Also note that .. image:: is left-aligned by default. Use :align: center or :align: right to place the image center or to the right, as needed. Note that by default, left and center images are not floated; but right ones are (this explains why the text of this paragraph is wrapping on the third image above).

Setting Anchor Text

As with any directive, the anchor text for a figure should be set using the :name: option as a matter of good usage. However, with figures there is the further consideration that links to a figure with the explicit (bad) form — .. _exp-anchor-form: — will jump to the scroll position on the page of the figure caption(!), not the top of the image itself. As an illustration, the figure at the start of the “Layout” topic is linked to here with:

• an explict link, and

• one using the :name option:.

Try the two links to see the difference.