10 Figures

10.1 Use figures with the file type SVG (ASM-57)

SVG is the preferred format for figures.

Exceptions

If you cannot use figures of the file type SVG, use the file type PNG.

Example

There is no example.

Source

ASAM specific rule.

10.2 Naming conventions for files of figures (ASM-81)

The following rules apply:

  • File names of figures shall be named based on the caption of the figures.

  • Lowercase letters shall be used for file names.

  • Underscores _ shall be used as separators.

  • The prefix fig shall be used in file names to identify that the file is an image.

  • Additional qualifiers may be used, for example, cs for core specification.

Exceptions

For long captions the file name may be shortened.

Example without an additional qualifier

Caption of the figure: Port definition interfaces of the framework configuration object model
File name:             fig_port_definition_interfaces.svg

Example with an additional qualifier

Caption of the figure: Port definition interfaces of the framework configuration object model
File name:             fig_cs_port_definition_interfaces.svg

Source

ASAM specific rule.

10.3 Make sure that all included figures are shown correctly (ASM-28)

Exceptions

There are no exceptions.

Example

There is no example.

Source

ASAM specific rule.

10.4 Make sure that there are no unused figures in the repository (ASM-29)

Exceptions

There are no exceptions.

Example

There is no example.

Source

ASAM specific rule.

10.5. Use one folder _images (ASM-92)

An _images folder shall be created in the content folder of the repository if the document contains images. A subfolder shall be created in the _images folder for every section of the document that contains images. The subfolder shall be named like the subfolder of the section where the AsciiDoc files are located, for example, 09_geometry. The subfolder shall contain the images specific for this section.

Exceptions

There are no exceptions.

Example

content/
├── _images/
│   ├── ...
│   ├── 09_geometry/
│   │   ├── fig_adding_primitives.svg
│   │   ├── fig_arc.svg
│   │   ├── fig_curve_1.svg
│   │   └── ...
│   └── ...
├── ...
├── 09_geometry/
│   ├── 09_00_geometry.adoc
│   ├── 09_01_road_reference_line.adoc
│   ├── 09_02_straight_line.adoc
│   └── ...
└── ...

Source

ASAM specific rule.

10.6 Add figures in a defined sequence (ASM-134)

Elements for figures shall be added in the following sequence:

  1. An anchor (see rule ASM-78)

  2. A caption to express the essence of the figure

  3. An include of the image (see rule ASM-81, see docs.asciidoctor.org/asciidoc/latest/macros/images/)

  4. A blank line

  5. A description (see rule ASM-59)

Exceptions

There are no exceptions.

Example

Code

[#fig-ad5fd969-c02a-48fc-97dd-84228f630df6]
.This is the caption of the figure
image::coo_sys_inertial_example.png[Alternative text]

<<fig-96f0f940-36bb-4a8c-8d98-98ff3e71c9bb>> shows something that shall be explained in more detail.

Result

Alternative text
Figure 1. This is the caption of the figure

Figure 1 shows something that shall be explained in more detail.

Source

ASAM specific rule.

10.6.1 Add an alternative text for every figure with defined size (ASM-118)

  • Add an alternative text to a figure to trigger the scaling of the figure during the rendering process.

  • If there is no specific alternative text available, use img as default.

  • Figures without alternative text will not be scaled.

Exceptions

There are no exceptions.

Example

Code 3. Example With alternative text
[#fig-fe4294ac-022d-4687-bc13-11798a9b4ce5]
.The UML notification
image::images/uml_notation.drawio.svg[UML notification, 1100]
Code 4. Example With default text img
[#fig-69e40be7-7a2a-439f-b1df-db19679675ad]
.This is the caption of the figure
image::images/uml_notation.drawio.svg[img, 1100]

Source

ASAM specific rule.

10.6.2 Add a description for each figure (ASM-59)

  • The description shall be below the figure.

  • The description shall start with the text [Reference to figure] shows.

  • The description shall not have an initial article.

  • The description shall not contain references to the placement of the figure, for example, before or below.

  • A reference to a figure shall be realized by a figure anchor. Figure references are displayed as a link.

Exceptions

Decorative figures shall not have a description, for example, the ASAM logo.

Example

Code

<<fig-7558b905-679d-4fb9-affa-3b3b72025a18>> shows the offset of the center lane away from the road reference line.

Result

Figure 58 shows the offset of the center lane away from the road reference line.

Source

ASAM specific rule.

10.7. Use global plantuml-format attribute (ASM-94)

The images generated from the PlantUML diagrams during the creation of the output document shall have SVG format. This is globally configured with the document attribute :plantuml-format: in the document header.

Exceptions

There are no exceptions.

Example

:plantuml-format: svg

Source

ASAM specific rule.