Diagram Generation Labs
The syside viz commands generate SysML v2 diagrams from models using Modeler CLI’s
built-in visualization engine.
Syside Labs
Diagram generation is an early-stage feature under Labs. The command surface and output may change as the engine matures.
Learn about:
Single Element Diagrams: turn any model element into a diagram with a single command
Model View Diagrams: repeatable diagrams defined as views in the model
Multi-File Models: render models that span many files and directories
CI Automation: generate diagrams in pipelines
Before You Start
Make sure Modeler CLI is installed and activated
Select or create a SysML v2 model (
.sysml) for generating diagrams
This guide uses Example Models.
Hint
Structure model files into directories (e.g., folder per subsystem). syside viz
loads models recursively, so the directory structure can help control what appears
in the diagrams (see Multi-File Models).
Single Element Diagrams
Any element of a model can be turned into a diagram:
abstract part def PhysicalComponent {
attribute mass :> ISQ::mass;
}
part def Airframe :> PhysicalComponent {
attribute material : String;
}
Airframe.svg
A single command generates the image above:
syside viz element DroneMissionModel.sysml --name "DroneMission::Components::Airframe" -o Airframe.svg
The diagram shows the element and everything it contains: owned elements like
capacity, and inherited ones like the ^mass attribute and the ^pwrOut port.
Hint
SysML v2 uses the ^ prefix to mark inherited elements in diagrams. Inherited
rows can be hidden per view with the showInheritedRows attribute, or globally with the
viz.compartments.show_inherited_rows configuration setting.
The --name argument selects the element to render: its qualified name becomes the
root node of the diagram. The argument can be repeated to draw several elements as root
nodes in one diagram.
The -o argument controls where the generated diagram is saved. It can be an absolute
path (e.g., C:\diagrams\Battery.png) or relative to the folder from which the
command is executed. Image format is derived from the output file extension, and can be
one of the following: svg, png, or jpeg.
Finding the Qualified Name
The qualified name is the path of names from the root to the element, joined with
::.
package DroneMission {
package Structure {
part def <QC> Quadcopter :> Drone {
part powertrain : Subsystem;
}
}
}
Here, the full qualified name of powertrain is
DroneMission::Structure::Quadcopter::powertrain.
Hint
The Syside Modeler extension shows the qualified name when hovering over an element in the editor:
Names with spaces or special characters are quoted in SysML, and the quotes are part of
the qualified name: DroneMission::Interactions::MissionHandshake::'Ground Station'.
Wrap such names in double quotes for the shell:
syside viz element drone-mission/ --name "DroneMission::Interactions::MissionHandshake::'Ground Station'"
If no element matches, the command lists the closest matching names.
Customizing Presentation
By default, an element renders as a general view, in the nested style, with full depth. Each of these defaults can be changed from the command line.
syside viz element drone-mission/ --name "DroneMission::Components::Drone" --render tree --depth 2 --output-file Drone_tree.svg
The --view argument selects another view kind, such as interconnection or state_transition.
The --render tree argument draws the decomposition as a tree instead of nesting
children.
The --depth argument limits how many levels of descendants appear.
Warning
Argument parser rejects a bare -d -1 flag. For infinite depth, use the expanded
form: --depth=-1.
Default configuration
Custom styling with --config syside.toml
The command line covers the basics. The rest of the presentation, such as color customization, filtering and compartment visibility, is configurable through SysML views or a configuration file:
[viz.style.group.part_usage]
members = ["PartUsage"]
fill_header = "#88b7e3ff"
fill_body = "#f7f9ffff"
text_keyword = "#1f4373ff"
[viz.style.group.part_definition]
members = ["PartDefinition"]
fill_header = "#5d9ddbff"
fill_body = "#f7f9ffff"
text_keyword = "#163366ff"
[viz.style.group.attribute_usage]
members = ["AttributeUsage"]
fill_header = "#b1bcd0ff"
fill_body = "#f7f8fbff"
text_keyword = "#363f55ff"
The configuration can be passed to syside viz with the --config flag:
syside viz element drone-mission/ --name "DroneMission::Components::Drone" --render tree --depth 2 --config syside.toml --output-file Drone_styled.svg
For every flag and default, see the viz element reference. For every configuration setting, see the viz configuration reference.
Model View Diagrams
SysML v2 makes diagrams part of the model itself. Views, written in the same standardized language, select the content, the view kind, and the output file of each diagram. With the model as the single source of truth, the same command reproduces the same diagrams for everyone. This is the recommended approach for repeatable, version-controlled diagram generation. See Diagram Views for defining views and finetuning their output.
view electrical_quadcopter : InterconnectionView {
expose DroneMission::Structure::Quadcopter::*::**;
filter not (@ Domain) or @ ElectricalDomain;
attribute fileName = "01_electrical_quadcopter";
}
The following command renders every view found in the model into the diagrams
directory, one image per view:
syside viz view drone-mission/ --output-dir diagrams
Warning
Views must be named to render: anonymous views are skipped with a warning.
Selecting Views
The --name argument limits rendering to views at or under a qualified name. The
argument accepts both views and packages: the qualified name of a view renders that one
diagram, while the qualified name of a package renders every view under the package:
syside viz view drone-mission/ --format png --output-dir diagrams --name DroneMissionDiagrams::electrical_quadcopter
Customizing Output
Output can be configured in two places: on the command line, applicable for a single
run, and in the model, for each view. On the command line, --output-dir selects
where the diagrams are written (default: ./output), and --format sets the image
format for all views at once.
In the model, each view carries its own configuration as regular SysML v2 attributes:
view hierarchy_quadcopter : GeneralView {
expose DroneMission::Structure::Quadcopter::**;
filter @ PartDefinition or as PartUsage hastype PartUsage;
attribute depth = 2;
attribute maxCompartmentEntries = 0;
attribute showAnnotationRows = false;
attribute fileName = "07_hierarchy_quadcopter";
render asTreeDiagram;
}
This view renders as a two-level deep tree into 07_hierarchy_quadcopter.svg. A view
without a fileName is written as diagram-<view name>. See Configurable
Attributes for all available customization options.
Styling works the same as for single element diagrams, using the --config flag to pass a configuration
file.
Note
With three places to define a setting, conflicts are resolved by a fixed order
of precedence: command-line arguments win over view
attributes, and view attributes win over the configuration file (e.g., a view’s
fileType attribute beats the configured format, but --format beats both).
See the viz view reference for a full list of available arguments and default values.
Expose Modes
In SysML v2, a view exposes a portion of the model and filters it down to a flat list of exposed elements: the elements allowed to appear in the output. For textual output, that list is the final answer. A diagram, however, has to map the exposed elements back onto the containment hierarchy, and the mapping becomes ambiguous as soon as an element passes the filter while its parent does not. The expose mode selects the mapping strategy.
The example model runs into this with its medical delivery variant. The medkit is cargo, not a component of the drone, so it is modeled as an item:
part def MedicalQuadcopter :> Quadcopter {
item medkit {
part sampleCooler : SampleCooler { @ELEC; }
part trackingBeacon : TrackingBeacon { @ELEC; }
}
}
Each mode resolves the conflict differently:
The default mode. A filtered element is dropped together with its whole subtree:
the medkit takes sampleCooler and trackingBeacon with it.
Useful for pruning the architecture cleanly.
view expose_subtree : GeneralView {
expose DroneMission::Structure::MedicalQuadcopter::**;
filter (
as SysML::PartUsage hastype SysML::PartUsage or
as SysML::PartDefinition hastype SysML::PartDefinition
);
attribute exposeMode = "subtree";
attribute fileName = "08_expose_subtree";
}
Filtered elements are dropped, but their exposed descendants are promoted to the
view frame, prefixed with their origin path (medkit::sampleCooler). Nothing the
filter allows is lost.
Useful in cases where the diagram must account for every exposed element.
view expose_promoted : GeneralView {
expose DroneMission::Structure::MedicalQuadcopter::**;
filter (
as SysML::PartUsage hastype SysML::PartUsage or
as SysML::PartDefinition hastype SysML::PartDefinition
);
attribute exposeMode = "promoted";
attribute fileName = "09_expose_promoted";
}
Containment is not reconstructed at all: every exposed element renders as an independent sibling. This is the flat list shown literally.
Useful for inventories and catalogs.
view expose_flat : GeneralView {
expose DroneMission::Structure::MedicalQuadcopter::**;
filter (
as SysML::PartUsage hastype SysML::PartUsage or
as SysML::PartDefinition hastype SysML::PartDefinition
);
attribute exposeMode = "flat";
attribute fileName = "10_expose_flat";
}
The example model changes the mode using the exposeMode attribute. It can also be
set per run with --expose, or globally with the viz.expose.mode
configuration setting.
Multi-File Models
Models that span several files render the same way: pass the directories, and every
.sysml file inside is collected recursively. Paths can be files, directories, or
glob patterns, mixed freely; overlapping paths are collected only once. File discovery
follows the same rules as syside check.
syside viz view drone-mission/DroneMissionModel.sysml drone-mission/DroneMissionViews.sysml --format svg --output-dir diagrams
Passing only part of a model breaks its references to the files left out. Each broken
reference is reported as a reference-error naming the missing namespace, and no
diagrams are produced until all references resolve.
Hint
If parts of the model live outside the passed directories, such as an external
library or a shared package, add their locations with --include. Included paths
join the positional paths in file discovery, so views found there render like any
other:
syside viz view drone-mission/ --include lib/ --format svg --output-dir diagrams
Excluding Files
In larger repositories, passing whole directories quickly collects more than intended.
Validation runs on everything collected, so a single broken work-in-progress file aborts
rendering for every stable model in the tree. The --exclude argument removes files
or glob patterns from discovery:
syside viz view models/ --exclude "models/sandbox/**" --format svg --output-dir diagrams
Duplicate copies of a model are a quieter trap. When two collected files declare the same top-level element (e.g., a stable model and its archived copy), the copies shadow each other in the global namespace.
Warning
The CLI treats duplicate namespaces as warnings, not errors. They are reported, but do not prevent the CLI from generating diagrams. This can lead to unexpected non-deterministic behavior.
Exclude duplicate files when any such warnings appear.
For a model that always needs the same locations, set include and exclude in the
syside.toml file instead of repeating the flags. See
Shared Settings for details.
CI Automation
Diagram generation is fully headless: syside viz can run on any CI runner or
container where the CLI is installed and activated.
Runners can be licensed with a deployment key kept in the CI provider’s secret storage
(see Activate License in CI/CD), or, for air-gapped setups, with a license file
(see Offline Installation).
A typical pipeline job validates first, then renders:
syside check
syside viz view models/ --format svg --output-dir diagrams
Validating separately turns model errors into a validation failure with full diagnostics instead of an aborted render. A failed step exits with a non-zero code, which fails the pipeline (see exit codes). The output directory can be published as a pipeline artifact for review.
A shared syside.toml in the repository gives the pipeline and engineers’ machines
the same render settings. The CLI discovers the
file automatically, and --config selects one explicitly.
Renders are reproducible: the same model, configuration, and CLI version produce identical files.
Pin the CLI version used by the pipeline, as diagram output may change between releases while diagram generation is under Labs.
Example Models
The drone mission model is a small, complete example for trying the commands on this page. It contains ten defined views.