Visual Styling

Note

🔧 Intermediate / Architecture — Customize the appearance of elements and diagrams through colors, line styles, and themes.

Color Model

PyArchimate supports two color specification formats:

Hexadecimal colors

Standard 6-digit hex color codes (RGB):

fill_color = "#FF5733"  # Bright orange-red
line_color = "#2E86AB"  # Dark blue

Named colors

English color names (case-insensitive):

fill_color = "red"
line_color = "blue"
line_color = "DarkGreen"

Supported named colors include: red, blue, green, yellow, orange, purple, pink, brown, gray, white, black, and many more.

Per-Element Styling

You can customize the appearance of individual elements by setting their visual properties.

Setting fill color

from pyArchimate import Model, ArchiType

model = Model(name="Styled Model")
element = model.add_element(
    name="Important Process",
    element_type=ArchiType.BusinessProcess
)

# Set hex color
element.set_fill_color("#FFD700")  # Gold

# Or use a named color
element.set_fill_color("gold")

Getting fill color

color = element.get_fill_color()  # Returns "#FFD700" or "gold"

Setting line color and width

element.set_line_color("#000000")  # Black
element.set_line_width(3)  # 3-point width

Setting transparency

element.set_transparency(0.5)  # 50% transparent (alpha = 0.5)
element.set_transparency(0.0)  # Fully opaque
element.set_transparency(1.0)  # Fully transparent

Getting visual properties

fill = element.get_fill_color()
line = element.get_line_color()
width = element.get_line_width()
alpha = element.get_transparency()

Bulk Styling

Apply the same style to multiple elements

Use set_visual_style to apply a complete style dictionary:

style = {
    "fill_color": "#E8F4F8",
    "line_color": "#2E86AB",
    "line_width": 2,
    "transparency": 0.1
}

# Apply to multiple elements
for element in model.elements:
    if element.element_type == ArchiType.ApplicationService:
        element.set_visual_style(style)

Get all visual properties

visual_properties = element.get_visual_style()
# Returns: {"fill_color": "...", "line_color": "...", ...}

Model-Wide Themes

Set a default theme for the entire model. This serves as the base style for all elements, which you can then override on a per-element basis.

Setting a default theme

model = Model(name="Themed Model")

default_theme = {
    "fill_color": "#FFFFFF",   # White background
    "line_color": "#333333",   # Dark gray border
    "line_width": 1,
    "transparency": 0.0
}

model.set_default_theme(default_theme)

Overriding theme for specific elements

# Most elements use the default theme
regular_element = model.add_element(
    name="Regular",
    element_type=ArchiType.BusinessProcess
)

# But you can override for emphasis
important_element = model.add_element(
    name="Critical System",
    element_type=ArchiType.ApplicationService
)
important_element.set_fill_color("#FF6B6B")  # Red to highlight importance
important_element.set_line_width(3)

Round-Trip Preservation

When you read and write a model, all visual styling is preserved:

# Read a model with styling
model = Model.read("styled.archimate")

# Modify the model
element = model.get_element("some_id")
element.set_fill_color("#00FF00")

# Write back - all styling (original + new) is preserved
model.write("modified.archimate")

Visual styling survives export and re-import cycles in all supported formats.

Practical Example: Coloring by Layer

Here’s a practical example of styling elements based on their layer:

from pyArchimate import Model, ArchiType

model = Model(name="Layered Styling")

# Define color scheme by layer
layer_colors = {
    "business": "#FFE6CC",     # Light orange for Business
    "application": "#CCE5FF",  # Light blue for Application
    "technology": "#E6CCFF"    # Light purple for Technology
}

# Add elements with layer-based styling
business_process = model.add_element(
    name="Handle Order",
    element_type=ArchiType.BusinessProcess
)
business_process.set_fill_color(layer_colors["business"])

app_service = model.add_element(
    name="Order Service",
    element_type=ArchiType.ApplicationService
)
app_service.set_fill_color(layer_colors["application"])

tech_service = model.add_element(
    name="API Gateway",
    element_type=ArchiType.TechnologyService
)
tech_service.set_fill_color(layer_colors["technology"])

# Write styled model
model.write("layered.archimate")

Troubleshooting

Invalid color format

If you use an invalid color format (e.g., wrong hex syntax), the styling function will raise an error. Always use:

Hex: #RRGGBB (6 digits)
Named: English color name (case-insensitive)

Styling not visible in diagrams

If styling doesn’t appear in exported diagrams:

Ensure you saved the model after styling (model.write())
Check that your diagram tool respects custom styling (some tools may use predefined colors)
Verify the transparency value (0.0 = opaque, 1.0 = invisible)