Both connectors and cables accept an image mapping. WireViz places the image inside the native component box and optionally adds a caption underneath. Image geometry is controlled through Graphviz's HTML-like table layout. The defaults below come from Image in DataClasses.py, with rendering examples in the pinned advanced image guide.
Add a component image
This is a definition fragment. Supply the image file alongside the document or through the browser's asset workflow.
connectors:
X1:
pincount: 3
type: Sensor connector
image:
src: assets/sensor-plug.png
width: 120
caption: |
Mating-face view
Pin numbers shown from the front
An image is a visual reference; it does not define pin positions, connector geometry, or automatic connection points. Keep actual pin IDs and wiring in the connector and connection sections. State the viewing direction in the caption when a connector photograph or drawing could otherwise be ambiguous.
Complete image schema
| Field | Type | Meaning |
|---|---|---|
src |
String, required | Local image filename/path for native WireViz; an available imported asset path in the browser. |
width |
Integer | Image-cell width in points. The documented Graphviz range is 1–65535. |
height |
Integer | Image-cell height in points, with the same documented range. |
scale |
String | "false", "true", width, height, or both. |
fixedsize |
Boolean | Whether the image cell keeps a fixed size instead of treating dimensions as a minimum. |
bgcolor |
Color | Background of the image cell. |
caption |
Multiline text | Caption displayed in a separate cell below the image. |
width and height are diagram points, not source-image pixels. The dataclass does not implement an exhaustive numeric range validator; use the documented positive range. Quote the scale strings "true" and "false" so YAML does not turn them into booleans. fixedsize is deliberately a boolean.
Default scaling behavior
| Dimensions supplied | Default scale |
Default fixedsize when scale is omitted |
|---|---|---|
| Neither | "false" |
False-valued; use the image's natural size. |
| Width only | "true" |
True; calculate height from image aspect ratio. |
| Height only | "true" |
True; calculate width from image aspect ratio. |
| Width and height | both |
True; fit the specified dimensions independently. |
If you explicitly supply scale and omit fixedsize, the default becomes false even when dimensions are supplied. If fixedsize is true and only one dimension is available, WireViz reads the image aspect ratio to calculate the other dimension. If the image cannot be read for that calculation, the helper warns and assumes a square aspect ratio. Native image reading depends on Pillow and the installed Graphviz image support.
Choose the fitting behavior
scale |
Intended behavior |
|---|---|
"false" |
Do not scale the image. |
"true" |
Scale proportionally to fit the available image cell. |
width |
Scale to the available width. |
height |
Scale to the available height. |
both |
Scale to both cell dimensions, potentially changing the aspect ratio. |
With fixedsize: false, the dimensions are minimum cell sizes and content can enlarge the cell. With fixedsize: true, the image cell dimensions are fixed. Other rows, captions, and table borders still affect the overall component box size.
For a predictable thumbnail that keeps its proportions, specify one dimension and let the default proportional behavior apply. To fit proportionally inside a fixed rectangle, supply both dimensions and set both controls explicitly:
image:
src: assets/sensor-plug.png
width: 120
height: 80
scale: "true"
fixedsize: true
bgcolor: WH
Asset paths and exported files
Native parsing resolves relative component image paths using the input file directory and additional image search paths. The CLI also includes directories of prepended files. The Python API exposes image_paths for this purpose. Prefer unique, portable relative asset paths and keep them with the YAML in version control. Native path resolution.
The browser cannot read an arbitrary path on your computer from a YAML string. Import the referenced asset using the application's supported workflow and use its available name/path. A successful native absolute path is not automatically a portable browser asset reference.
Native SVG output embeds referenced images, and native HTML embeds the generated diagram. This makes those rendered outputs easier to distribute, but the editable YAML still needs its source assets. Image rendering in the interactive canvas can differ from the official engine rendering; use the generated output when reviewing image sizing and captions. See CLI outputs.