Utils#

Utility functions for visualkeras.

Note: This section is mainly useful for advanced customization of visualkeras, low-level rendering work, or contributing to the visualkeras codebase. Most users will not need these utilities directly.

Style Helpers#

visualkeras.utils.resolve_style(target, name, styles, defaults)[source]#

Resolve the effective style for a render target.

Styles are applied in two passes. Class-based rules are merged following the target’s method-resolution order, then name-based overrides are applied on top of that result.

Parameters:

  • target (Any) – Layer or render object whose style should be resolved.

  • name (str) – Concrete layer or node name used for name-based overrides.

  • styles (mapping) – Style mapping keyed by layer class or layer name.

  • defaults (dict) – Default style values to start from.

Returns:

Fully resolved style mapping for target.

Return type:

dict

visualkeras.utils.fade_color(color, fade_amount)[source]#

Return color darkened by fade_amount while preserving alpha.

Return type:

tuple

Parameters:

  • color (tuple) –

  • fade_amount (int) –

visualkeras.utils.get_rgba_tuple(color)[source]#

Normalize a color value into an (R, G, B, A) tuple.

Parameters:

color (Any) – Pillow-compatible color value. This may be a tuple, an integer-packed RGBA value, or a named or hex color string.

Returns:

Four-item RGBA tuple.

Return type:

tuple

visualkeras.utils.get_keys_by_value(d, v)[source]#

Yield all keys in d whose value equals v.

visualkeras.utils.self_multiply(tensor_tuple)[source]#

Multiply the numeric entries of a shape-like tuple together.

None values are ignored so partially specified tensor shapes can still be reduced into a usable best-effort product.

Parameters:

tensor_tuple (tuple) – Shape-like tuple whose entries should be multiplied.

Returns:

Product of the non-None entries, or 0 when no numeric entries are available.

Return type:

int

Drawing Primitives#

class visualkeras.utils.RectShape[source]#

Bases: object

Base rectangle-like drawing primitive used by multiple renderers.

This class stores shared geometry and color state for simple shapes drawn by the graph, layered, and utility rendering code. It is primarily an internal helper, but it appears in the API reference because the utility page exposes the public drawing primitives directly.

x1: int#
x2: int#
y1: int#
y2: int#
__init__()[source]#
style: dict = None#
property fill#
property outline#
class visualkeras.utils.Box[source]#

Bases: RectShape

Rectangular layer primitive with optional 3D depth or rotation.

Box is the main volumetric drawing primitive used by layered-style renderers. It can render flat rectangles, classic offset-depth boxes, or rotated 3D boxes while also exposing projected face coordinates for image and logo placement.

de: int#
shade: int#
rotation: Optional[float] = None#
get_face_quad(face_index)[source]#

Return the projected quadrilateral for a visible box face.

Parameters:

face_index (int) – Face identifier where 0 is front, 1 is back, 2 is right, 3 is left, 4 is top, and 5 is bottom.

Returns:

Four projected (x, y) coordinates for the requested face, or an empty list if the face projection is not available.

Return type:

list of tuple

draw(draw, draw_reversed=False)[source]#
Parameters:

  • draw (<module 'PIL.ImageDraw' from '/home/docs/checkouts/readthedocs.org/user_builds/visualkeras/envs/latest/lib/python3.11/site-packages/PIL/ImageDraw.py'>) –

  • draw_reversed (bool) –

class visualkeras.utils.Circle[source]#

Bases: RectShape

Circular node primitive used by graph-style renderings.

This shape is typically used for graph nodes that should read as compact points rather than volumetric boxes.

draw(draw)[source]#
Parameters:

draw (<module 'PIL.ImageDraw' from '/home/docs/checkouts/readthedocs.org/user_builds/visualkeras/envs/latest/lib/python3.11/site-packages/PIL/ImageDraw.py'>) –

class visualkeras.utils.Ellipses[source]#

Bases: RectShape

Ellipsis marker used when neuron counts are truncated visually.

Graph view uses this helper when a layer is too large to render every neuron marker individually.

draw(draw)[source]#
Parameters:

draw (<module 'PIL.ImageDraw' from '/home/docs/checkouts/readthedocs.org/user_builds/visualkeras/envs/latest/lib/python3.11/site-packages/PIL/ImageDraw.py'>) –

class visualkeras.utils.ColorWheel(colors=None)[source]#

Bases: object

Assign repeatable colors to layer classes from a finite palette.

This helper is useful when the caller wants deterministic but lightweight default colors without maintaining a full explicit color map.

Parameters:

colors (list) –

__init__(colors=None)[source]#
Parameters:

colors (list) –

get_color(class_type)[source]#

Return a stable palette color for class_type.

Parameters:

class_type (type) –

class visualkeras.utils.Ribbon(x1, y1, x2, y2, de, width, color, shade_step)[source]#

Bases: object

Connector primitive that draws a shaded ribbon between two points.

Ribbons are mainly used where a connector should read as a filled geometric transition instead of a simple line.

__init__(x1, y1, x2, y2, de, width, color, shade_step)[source]#
draw(draw)[source]#

Draw the ribbon onto an aggdraw canvas.

Parameters:

draw (Draw) –

Image Composition#

visualkeras.utils.vertical_image_concat(im1, im2, background_fill='white')[source]#

Stack two images vertically on a shared background.

Parameters:

  • im1 (PIL.Image.Image) – Image placed on top.

  • im2 (PIL.Image.Image) – Image placed below im1.

  • background_fill (Any, default='white') – Background color used for the combined canvas.

Returns:

Vertically concatenated image.

Return type:

PIL.Image.Image

visualkeras.utils.linear_layout(images, max_width=-1, max_height=-1, horizontal=True, padding=0, spacing=0, background_fill='white')[source]#

Arrange images in a wrapped horizontal or vertical strip.

Parameters:

  • images (list) – Sequence of PIL.Image objects to arrange.

  • max_width (int, default=-1) – Maximum layout width. This is only enforced in horizontal mode.

  • max_height (int, default=-1) – Maximum layout height. This is only enforced in vertical mode.

  • horizontal (bool, default=True) – If True, lay out images left to right and wrap into new rows when necessary. If False, lay out images top to bottom and wrap into new columns.

  • padding (int, default=0) – Outer padding around the full layout.

  • spacing (int, default=0) – Gap between adjacent images.

  • background_fill (Any, default='white') – Background color for the layout canvas.

Returns:

Composite image containing the arranged inputs.

Return type:

PIL.Image.Image

visualkeras.utils.resize_image_to_fit(image, target_width, target_height, fit_mode)[source]#

Resize an image to fit a target box using a named fit strategy.

Parameters:

  • image (PIL.Image.Image) – Source image to resize.

  • target_width (int) – Target width in pixels.

  • target_height (int) – Target height in pixels.

  • fit_mode ({'fill', 'contain', 'cover', 'match_aspect'}) – Strategy used to fit the image into the target box.

Returns:

Resized image prepared for the requested fit mode.

Return type:

PIL.Image.Image

visualkeras.utils.apply_affine_transform(target_img, source_img, quad, fit_mode)[source]#

Project source_img onto a quadrilateral within target_img.

Parameters:

  • target_img (PIL.Image.Image) – Destination image that receives the transformed source.

  • source_img (PIL.Image.Image) – Source image to project.

  • quad (list) – Four (x, y) points defining the destination quadrilateral.

  • fit_mode (str) – Fit mode passed through to resize_image_to_fit() before the projection is applied.

Logo Helpers#

Draw a logo image onto one face of a rendered box.

Parameters:

  • img (PIL.Image.Image) – Target image that will receive the logo.

  • box (Box) – Rendered box whose projected face will be used as the destination.

  • logo_img (PIL.Image.Image) – Logo image to place on the box face.

  • group (dict) – Logo-group configuration containing placement options such as axis, size, corner, and padding.

  • draw_volume (bool) – Whether the target box is being rendered volumetrically.

  • draw_reversed (bool, default=False) – Whether the layered perspective is reversed.

visualkeras.utils.draw_logos_legend(img, logo_groups, legend_config, background_fill, font, font_color)[source]#

Append a legend describing configured logo groups.

Parameters:

  • img (PIL.Image.Image) – Base image that may receive a legend below it.

  • logo_groups (sequence of dict) – Logo-group definitions used by the renderer.

  • legend_config (bool or dict) – Legend toggle or configuration mapping.

  • background_fill (Any) – Background color used for the legend canvas.

  • font (PIL.ImageFont.ImageFont) – Font used for legend labels.

  • font_color (Any) – Text color used for legend labels.

Returns:

Original image when no legend is requested, otherwise the image with an appended legend.

Return type:

PIL.Image.Image