Functional#

Functional view visualization for neural networks.

Overview#

The functional renderer combines the best of layered and graph visualization: it maintains layer-level structure while showing computational connections. This makes it ideal for Keras Functional models with skip connections, multi-branch architectures, and complex topologies.

When to use:

  • Keras Functional API models with skip connections

  • Multi-input or multi-output architectures

  • Models with parallel branches (e.g., Inception modules)

  • ResNet-style architectures with residual connections

  • Models where both layer structure and connections matter

When NOT to use:

  • Simple sequential models (use layered mode)

  • Models where pure computational graph is important (use graph mode)

  • Very wide parallel models (graph mode may be clearer)

API Reference#

visualkeras.functional.functional_view(model, to_file=None, color_map=None, background_fill='white', padding=20, column_spacing=80, row_spacing=40, component_spacing=80, connector_fill='gray', connector_width=2, connector_arrow=False, connector_padding=5, min_z=20, min_xy=20, max_z=400, max_xy=2000, scale_z=1.5, scale_xy=4.0, one_dim_orientation='z', sizing_mode='balanced', dimension_caps=None, relative_base_size=20, text_callable=None, text_vspacing=4, font=None, font_color='black', add_output_nodes=False, layout_iterations=4, virtual_node_size=12, render_virtual_nodes=False, draw_volume=False, orientation_rotation=None, shade_step=10, image_fit='fill', image_axis='z', layered_groups=None, logo_groups=None, logos_legend=False, styles=None, *, simple_text_visualization=False, simple_text_label_mode='below', collapse_enabled=False, collapse_rules=None, collapse_annotations=True, options=None, preset=None)[source]#

Render a functional model using a graph-aware layered layout.

This renderer sits between layered view and graph view. It preserves more layer-level geometry than a pure topology diagram while still handling branches, merges, multi-input paths, and other functional-model structure.

Parameters:

  • model (Any) –

    Keras model instance to visualize.

    Functional view is most useful when the model has a meaningful graph structure that would be lost in a strictly sequential rendering, but you still want the output to feel like an architecture diagram rather than a generic node-link graph.

  • to_file (str, optional) –

    Path to save the rendered image. The image format is inferred from the file extension.

    The rendered PIL.Image is returned whether or not this value is provided. Use this when you want to save the output and keep working with the in-memory image in the same call.

  • color_map (mapping, optional) –

    Mapping from layer class to broad style values such as fill and outline.

    This is the quickest way to create a consistent color language by layer type. It is best for coarse styling rules, while styles is better for per-layer control.

  • background_fill (Any, default='white') –

    Background color for the final image.

    This accepts any Pillow-compatible color value. Choose a background that keeps layer boxes, connectors, and annotation text easy to read.

  • padding (int, default=20) –

    Outer padding around the full diagram in pixels.

    Increase this when labels, groups, or legends feel too close to the canvas edge. Padding affects the whole composition rather than the gaps between nodes inside the layout.

  • column_spacing (int, default=80) –

    Horizontal spacing between layout ranks.

    This is one of the main controls for how open the diagram feels from left to right. Larger values improve readability in wide branching graphs, while smaller values make the figure more compact.

  • row_spacing (int, default=40) –

    Vertical spacing between nodes within the same rank.

    Use this to manage crowded parallel branches. It works together with node size, text labels, and connector routing.

  • component_spacing (int, default=80) –

    Spacing between disconnected graph components.

    This matters when the renderer splits a model into separate connected subgraphs or when synthetic nodes create distinct visual blocks.

  • connector_fill (Any, default='gray') –

    Color used for connector paths between nodes.

    Neutral connector colors tend to work well because the boxes themselves already communicate most of the layer semantics.

  • connector_width (int, default=2) –

    Line width used for connectors.

    Increase this for exported figures, large canvases, or diagrams where the connector paths need more visual weight.

  • connector_arrow (bool, default=False) –

    If True, draw directional arrowheads on connectors.

    Arrowheads can be helpful for teaching material or graphs where the direction of flow is not already obvious from the layout.

  • connector_padding (int, default=5) –

    Padding reserved around nodes when routing connectors.

    This helps prevent connectors from appearing glued to the box edges and gives routed paths a cleaner look.

  • min_z (int, default=20) –

    Minimum rendered depth in pixels for a layer box when volumetric rendering is used.

    This prevents channel-light layers from collapsing into thin slivers. It matters most when draw_volume is enabled.

  • min_xy (int, default=20) –

    Minimum rendered width and height in pixels for a layer box.

    A reasonable minimum keeps small layers visible even when the model also contains very large tensors.

  • max_z (int, default=400) –

    Maximum rendered depth in pixels for a layer box.

    Use this to keep channel-heavy layers from dominating the visual depth of the diagram.

  • max_xy (int, default=2000) –

    Maximum rendered width and height in pixels for a layer box.

    This cap protects the layout from becoming impractically large when a model contains very large spatial dimensions or long sequences.

  • scale_z (float, default=1.5) –

    Multiplier applied to the depth dimension before clamping.

    Increase this when channel depth should read more strongly in the figure. Reduce it when depth cues feel exaggerated.

  • scale_xy (float, default=4.0) –

    Multiplier applied to width and height dimensions before clamping.

    This is a main control for the apparent size of rendered layer boxes. Lower values keep dense graphs manageable, while higher values make individual nodes easier to inspect.

  • one_dim_orientation ({'x', 'y', 'z'}, default='z') –

    Axis used when rendering one-dimensional layers.

    This affects how dense or flattened outputs are represented visually in mixed architectures that combine convolutional and vector-like stages.

  • sizing_mode ({'accurate', 'balanced', 'capped', 'logarithmic', 'relative'}, default='balanced') –

    Strategy used to convert tensor dimensions into rendered sizes.

    balanced is the default because it usually produces readable functional diagrams without letting a few extreme layers dominate the canvas. The other modes trade realism against compactness in different ways.

  • dimension_caps (mapping, optional) –

    Custom caps used by sizing modes that support them. Supported keys are channels, sequence, and general.

    This is useful when a small number of large layers would otherwise make the rest of the graph difficult to compare.

  • relative_base_size (int, default=20) –

    Base pixel unit used by relative sizing mode.

    In relative mode, a dimension of one maps directly to this many pixels, subject to minimum and maximum bounds.

  • text_callable (callable, optional) –

    Callable receiving (layer_index, layer) and returning (text, above) for per-layer labels.

    This is the main hook for custom annotations such as layer names, block roles, or tensor shapes. Built-in helpers are available in visualkeras.options.LAYERED_TEXT_CALLABLES.

  • text_vspacing (int, default=4) –

    Vertical spacing between lines produced by text_callable.

    Increase this for multiline labels that feel cramped. Smaller values help conserve vertical space in dense graphs.

  • font (PIL.ImageFont.ImageFont, optional) –

    Font used for labels, annotations, and legends where applicable.

    A custom font is useful when the figure needs to match an existing visual style for documentation or publication.

  • font_color (Any, default='black') –

    Text color used for labels and related annotations.

    This should contrast clearly with the background and any group overlays.

  • add_output_nodes (bool, default=False) –

    If True, add explicit output nodes even when the graph can end on a real layer.

    This can make complex multi-output diagrams easier to read because the termination points become visually explicit.

  • layout_iterations (int, default=4) –

    Number of refinement passes used by parts of the layout pipeline.

    More iterations can improve ordering or collision handling in difficult graphs, but they also increase render time.

  • virtual_node_size (int, default=12) –

    Size used for virtual nodes inserted during long-edge normalization.

    This matters only when virtual nodes are rendered or when their size influences layout spacing.

  • render_virtual_nodes (bool, default=False) –

    If True, draw virtual routing nodes that are otherwise only used internally by the layout algorithm.

    This is mainly useful for debugging or for highly explicit topology diagrams where routing helpers should remain visible.

  • draw_volume (bool, default=False) –

    If True, render layer boxes with 3D depth cues. If False, use flat 2D rectangles.

    Flat mode is usually easier to read in complex functional graphs. Volumetric mode can be effective for presentation graphics or models where tensor depth is an important part of the explanation.

  • orientation_rotation (float, optional) –

    Optional rotation applied to volumetric boxes.

    This lets you change the apparent viewing angle of 3D nodes when the default perspective does not suit the figure.

  • shade_step (int, default=10) –

    Amount of shading variation used for 3D faces and related effects.

    Larger values create stronger contrast between faces. Smaller values produce a flatter and subtler look.

  • image_fit ({'fill', 'contain', 'cover', 'match_aspect'}, default='fill') –

    Default fit mode for images injected through styles.

    Choose a mode based on whether you prefer full coverage, preserved aspect ratio, or exact fill behavior.

  • image_axis ({'x', 'y', 'z'}, default='z') –

    Default axis used when rendering per-layer images in volumetric mode.

    This determines which face of a 3D node should receive an embedded image unless a per-layer override is supplied through styles.

  • layered_groups (sequence of dict, optional) –

    Group definitions used to draw labeled background regions behind sets of nodes.

    Groups are useful for separating architectural stages or conceptual blocks without changing the graph structure itself.

  • logo_groups (sequence of dict, optional) –

    Logo placement definitions used to add icons or other overlays to selected nodes.

    This is mainly intended for presentation graphics and other highly styled figures.

  • logos_legend (bool or dict, default=False) –

    If truthy, render a legend describing entries supplied through logo_groups.

    A simple boolean enables the default legend behavior. A mapping allows more control over legend layout.

  • styles (mapping, optional) –

    Fine-grained style overrides keyed by layer name or layer class.

    Use this for per-layer images, local color overrides, box text styling, volumetric settings, and other adjustments that are too specific for color_map.

  • simple_text_visualization (bool, default=False) –

    If True, render nodes primarily as text blocks instead of sized boxes.

    This mode is useful when a compact textual diagram communicates the architecture better than geometric layer boxes.

  • simple_text_label_mode ({'below', 'inside'}, default='below') –

    Placement mode for labels in simple-text visualization.

    below keeps text outside the box area, while inside produces a tighter and more schematic layout.

  • collapse_enabled (bool, default=False) –

    If True, enable collapsing of repeated layers or repeated blocks according to collapse_rules.

    Collapsing is useful for models with repeated motifs such as residual stacks, repeated convolution blocks, or Transformer-style repetition.

  • collapse_rules (sequence of mapping, optional) –

    Explicit rules describing which repeated patterns may be collapsed.

    Each rule declares a kind, a selector, and a repeat_count. Optional label and annotation fields let you control how the collapsed block is described in the rendered figure.

  • collapse_annotations (bool, default=True) –

    If True, draw annotations that describe collapsed regions.

    Disable this when you want the cleaner layout benefits of collapsing without additional explanatory text.

  • options (FunctionalOptions or mapping, optional) –

    Configuration bundle applied after preset and before explicit keyword arguments.

    This is the preferred way to reuse a functional style across multiple models or notebooks.

  • preset (str, optional) –

    Name of a preset from visualkeras.FUNCTIONAL_PRESETS. Functional mode currently provides default, compact, and presentation.

    Presets are intended as convenient starting points. They can be refined further with options and explicit overrides.

Returns:

Rendered functional diagram.

Return type:

PIL.Image.Image

Notes

Configuration precedence is preset followed by options followed by explicit keyword arguments.

Full documentation: https://visualkeras.readthedocs.io/en/latest/api/functional.html

Configuration Options#

Use visualkeras.options.FunctionalOptions when you want to bundle functional layout, connector routing, collapse behavior, and related styling in one reusable object. Curated presets are available through visualkeras.options.FUNCTIONAL_PRESETS.

Key Parameters#

Core Parameters

  • model: Keras Functional model instance

  • to_file: Path to save output (optional)

  • preset: Use preset configuration (‘default’, ‘compact’, ‘presentation’)

  • options: FunctionalOptions object for bundled configuration

Layout Control

  • column_spacing: Space between columns (default: 60)

  • row_spacing: Space between rows (default: 30)

  • component_spacing: Space between components (default: 100)

  • padding: Border space (default: 10)

Styling

  • color_map: Dict mapping layer types to {'fill': '...', 'outline': '...'}

  • connector_fill: Connection line color (default: ‘gray’)

  • connector_width: Line thickness (default: 1)

  • background_fill: Background color (default: ‘white’)

  • font_color: Text color (default: ‘black’)

Content Control

  • text_callable: Function or string key controlling layer labels

  • type_ignore: Layer types to skip

  • index_ignore: Layer indices to skip

Advanced

  • collapse_rules: Automatically collapse repeated layer sequences

  • sizing_mode: How to calculate layer sizes (‘accurate’, ‘balanced’, ‘logarithmic’)

  • styles: Per-layer style overrides

Collapse Rules#

Automatically collapse sequences of repeated layers:

collapse_rules = [
    {
        'kind': 'layer',
        'selector': keras.layers.Conv2D,
        'repeat_count': 3,
        'label': '3x Conv2D',
        'annotation_position': 'above',
    }
]

image = visualkeras.show(
    model,
    mode='functional',
    collapse_rules=collapse_rules
)

Usage Examples#

Basic Usage#

import visualkeras

image = visualkeras.show(model, mode='functional')
image.show()

With Presets#

# Presentation quality
image = visualkeras.show(model, mode='functional', preset='presentation')

# Compact for slides
image = visualkeras.show(model, mode='functional', preset='compact')

With Collapsed Layers#

collapse_rules = [
    {
        'kind': 'block',
        'selector': [keras.layers.Conv2D, keras.layers.BatchNormalization],
        'repeat_count': 2,
        'label': 'Conv Block (2x)',
    }
]

image = visualkeras.show(
    model,
    mode='functional',
    collapse_rules=collapse_rules,
    preset='presentation'
)

See Also#