Images

Images can be included in the comment with the image directive.

Description

The directive markup consists of an explicit markup start (".. ") followed by the type of the directive (image) and two colons.

(See also: Directives)

Principle

.. image::

Properties

  • The file path for the image source file is specified in the argument of the directive. As with hyperlink targets, the file path can begin immediately after that in the same line as the explicit markup start or in an indented text block (without empty lines in between). The file path can be specified absolutely or relatively and may not contain any spaces. (See: Absolute or relative file path as directive argument)
  • The image is displayed as wide as possible (=100%) according to the window width of the Library Manager. If the window width of the Library Manager is changed, the proportionality of the image is maintained.
  • A blank line is required between the directive and a preceding text body element (e.g. a paragraph with text).

Options

Optionally, the directive block can contain a flat field list with image options. The following options are recognized:

height: length

Height of the image.

Used to scale the image vertically. The width of the image is adjusted proportionally if possible.

  • Specification in px (with or without spaces):
    • The height of the displayed image always corresponds to the specified height of the image in px, regardless of the height and width of the Library Manager window. If the height of the Library Manager window is smaller than the specified image height, you can display the remaining part of the image by scrolling within the Library Manager.
    • The image width is at most as large as the window width of the Library Manager: If the Library Manager window is wide enough, the image is displayed proportionally. Otherwise the display is distorted.
    • The proportionality of the image therefore depends on the window width of the Library Manager.

width: length or percentage of the current line width

Width of the image.

Used to scale the image horizontally. The height of the image is adjusted proportionally if possible.

  • Specification in px (with or without spaces):
    • The width of the displayed image corresponds to the specified width of the image in px if possible but is at most as large as the window width of the Library Manager. This means that if the width of the Library Manager window is smaller than the specified image width, the image is only as wide as the Library Manager window.
    • The height of the image is adjusted proportionally to the specified image width.
    • The proportionality of the image therefore depends on the window width of the Library Manager.
  • Specification in % (with or without spaces):
    • The width of the displayed image takes up the specified percentage of the window width of the Library Manager.
    • The height of the image is adjusted proportionally to the image width.
    • The proportionality of the image is thus maintained.

align: „left“ or „right“

Alignment of the image.

The values "left" and "right" control the horizontal alignment of an image so that the image can float and the text can flow around it.

target: text (URI or reference name)

Turns the image into a reference ("clickable"). The argument of the option can be a URI (relative or absolute) or a reference name with an underscore suffix (e.g. name_).

scale: integer percentage

Uniform scaling factor of the image.

Used to scale the image proportionally.

  • Specification in % (with or without spaces):
    • The width and the height of the displayed image always correspond to the specified percentage of the original image size (i.e. the size of the graphic that is referenced in the file system), irrespective of the width and height of the Library Manager window. If the width or height of the Library Manager window is smaller than the specified image width or height, you can display the remaining part of the image by scrolling within the Library Manager.
    • The proportionality of the image is thus maintained.

If an image is included without a height or width option, the width of the displayed image corresponds to the window width of the Library Manager. The height of the image is adjusted proportionally to the image width. The image is displayed as large as possible. The proportionality of the image is maintained.

Absolute or relative file path as directive argument

You can specify both absolute and relative file paths in the argument of the image directive in order to reference images.

Specify an absolute file path if you have saved the image in an arbitrary folder in your file system. Specify a relative path if the image is integrated in the library project.

Images 1:

Forwarding the library file

If you integrate the images in the library project and use relative file paths and then forward the library project as a file, the required image information will be sent with it directly as part of the library project. If you use absolute file paths, the images must be forwarded separately and must exist at the place in the file system specified in the file path for the person who uses the library. The latter is also a static approach in which the organization and maintenance of the image information in the file system means additional work.

Absolute file path

e.g. C:\Tc3LibDocImages\SamplePicAbsolute.jpg

Images 2:

Relative file path

Requirement: TwinCAT 3.1.4022.22

 

e.g. ../../LibPics/SamplePicRelative.jpg

Integrating an image in the PLC project

1. Create a folder for images in the PLC project tree for a uniform storage place and clear project structure (e.g. LibPics).
2. Select the command Add > Existing element in the context menu of the folder.
3. In the file system, select the image (e.g. SamplePicRelative) and confirm the dialog.
The image is added to the PLC project and can be referenced in a reStructuredText comment in the documentation of a library object. (See: Examples)
When saving the PLC project as a library the image is saved with it in the library file (*.library/*.compiled-library). If the library is referenced in a PLC project, the image is displayed with it in the library manager. The image can be opened by double-clicking on the image in the library manager.

Solution Explorer:

Images 3:

Library Manager:

Images 4:

Samples

(In sample project: B_DocuElements\Images\FB_Libdoc_Images)

Absolute or relative file path as directive argument

(*
Absolute path

.. image:: C:\Tc3LibDocImages\SamplePicAbsolute.jpg
   :width: 70px

Relative path

.. image:: ../../LibPics/SamplePicRelative.jpg
   :width: 70px
*)

Images 5:

Left aligned image

(*
.. image:: C:\Tc3LibDocImages\SampleLib1\img11.jpg
   :width: 20%

Description of the function block. Description of the function block. Description of the function block.
Description of the function block. Description of the function block. Description of the function block.
Description of the function block. Description of the function block. Description of the function block.
Description of the function block. Description of the function block. Description of the function block.
*)

Images 6:

Floating image, left aligned

(*
.. image:: C:\Tc3LibDocImages\SampleLib1\img11.jpg
   :width: 20%
   :align: left

Description of the function block. Description of the function block. Description of the function block.
Description of the function block. Description of the function block. Description of the function block.
Description of the function block. Description of the function block. Description of the function block.
Description of the function block. Description of the function block. Description of the function block.
*)

Images 7:

Floating image, right aligned

(*
.. image:: C:\Tc3LibDocImages\SampleLib1\img11.jpg
   :width: 20%
   :align: right

Description of the function block. Description of the function block. Description of the function block.
Description of the function block. Description of the function block. Description of the function block.
Description of the function block. Description of the function block. Description of the function block.
Description of the function block. Description of the function block. Description of the function block.
*)

Images 8:

Inline images can be defined with an image directive in a substitution definition (see Substitution).