Core

Layout

class pinout.core.Layout(x=0, y=0, children=None, **kwargs)

Bases: pinout.core.Component, pinout.core.TransformMixin

Base class fundamentally grouping other components together.

This class is not designed to be used directly. Methods listed here are inherted by child classes and accessible via them.

Parameters

x (int, optional) – x-axis location, defaults to 0
y (int, optional) – y-axis location, defaults to 0
tag (string (must be valid css class name), optional) – css class tag, defaults to None

render_children()

Render SVG markup from ‘children’

Returns: SVG markup
Return type: string

StyleSheet

class pinout.core.StyleSheet(src, embed=False)

Bases: object

Include a cascading stylesheet.

This class should be added to a diagram via Diagram.add_stylesheet(). Relative paths are relative to the Python script, not the export destination. On export, if the path is relative, it is updated automatically to reflect the destination directory. On export, embedded stylesheets are copied into a <style> tag in the SVG output file.

Parameters

path (string) – Path to stylesheet file
embed (bool, optional) – Embed stylesheet in exported file, defaults to False

render()

Raw

class pinout.core.Raw(content)

Bases: object

Include arbitary code to the document

Parameters: content (string) – SVG code

Group

class pinout.core.Group(x=0, y=0, tag=None, **kwargs)

Bases: pinout.core.Layout

Group components together

Parameters

x (int, optional) – Coordinate of top-left point in x-axis, defaults to 0
y (int, optional) – Coordinate of top-left point in y-axis, defaults to 0
tag (string (must meet css class naming rules), optional) – CSS class, defaults to None

ClipPath

class pinout.core.ClipPath(children=None, **kwargs)

Bases: pinout.core.Group

Define a clip-path component

Once defined the clip-path can be appled to other components by referencing its uuid.

Parameters

x (int, optional) – Coordinate of top-left point in x-axis, defaults to 0
y (int, optional) – Coordinate of top-left point in y-axis, defaults to 0
tag (string (must meet css class naming rules), optional) – CSS class, defaults to None

..automethod:: ClipPath.render

return

SVG markup

rtype

string

SvgShape

class pinout.core.SvgShape(x=0, y=0, width=0, height=0, **kwargs)

Bases: pinout.core.Component, pinout.core.TransformMixin

Base class for components that have a graphical representation.

Classes that inherit from SvgShape can be considered the smallest building blocks of pinout. Along with text components, SvgShape classes represent the actual graphical elements that make up a diagram.

This class has no renderable output itself. Classes that inherit from it must provide their own unique render method. Whist its purpose is primarily as a building block for other classes, SvgShape can be used to reserve an area in components that don’t intrinsically have their own width and height (eg Group):

from pinout.core import Group, SvgShape

# Create an empty group
grp = diagram.add(Group())
print(f"group dimensions - width:{grp.width}, height:{grp.height}")

# output:
# >>> group dimensions - width:0, height:0

# Add an SvgShape instance to the group
grp.add(SvgShape(x=0, y=0, width=50, height=50))
print(f"group dimensions - width:{grp.width}, height:{grp.height}")

# output:
# >>> group dimensions - width:50.0, height:50.0

# The group now reports a size but does not render anything

Parameters

x (int, optional) – Location coordinate in x-axis, defaults to 0
y (int, optional) – Location coordinate in y-axis, defaults to 0
width (int, optional) – Width of the component, defaults to 0
height (int, optional) – Height of the component, defaults to 0
tag (string (must meet css class naming rules), optional) – CSS class, defaults to None

bounding_coords()

Coordinates representing a shape’s bounding-box.

Coordinates are relative to the parent component’s origin adn cater for scale and rotation transformations.

Returns: (x1, y1, x2, y2)
Return type: namedtuple (BoundingCoords)

bounding_rect()

Component’s origin coordinates and dimensions

Convenience method that expresses SvgShape.bounding_coords() as coordinates of the shape’s origin, width, and height.

Returns: (x, y, w, h)
Return type: namedtuple (BoundingRect)

Path

class pinout.core.Path(path_definition='', **kwargs)

SVG Path object

param path_definition

Path definition, defaults to “”

type path_definition

str, optional

class pinout.core.Rect(*args, corner_radius=0, **kwargs)

Bases: pinout.core.SvgShape

SVG <rect> object

Parameters: corner_radius (int, optional) – Round rectangle corners, defaults to 0

Text

class pinout.core.Text(content, **kwargs)

Bases: pinout.core.SvgShape

SVG <text> object

Parameters: content (string) – Text to be included in the tag

Image

class pinout.core.Image(src, dpi=72, embed=False, **kwargs)

Bases: pinout.core.SvgShape

Include an image in the diagram.

Valid bitmap formats are PNG and JPG - matching the SVG specifications. SVG images can be added via this Image class however they must provided at 1:1 dimensions and include their own dimensions in the <svg> tag. Additional care needs to be taken when incorporating SVG files as it is possible for CSS classes to clash.

Image size can be controlled by supplying a width and height property. Omiting one, or both, properties results in the supplied image’s pixel dimensions to be used.

Where supplied dimensions differ to the image’s pixel dimensions the image is scaled proportionally, and centred, to fit supplied dimensions.

Image instances can be added to any component that inherits from the Layout class:

from pinout.components.layout import Diagram
from pinout.core import Image

diagram = Diagram(800,400)

# Add an image to the diagram at coordinates (20,20)
diagram.add(Image("hardware.png", x=20, y=20))

If an image is to be used multiple times in a single diagram a single instance should be included into the diagram’s ‘defs’ and referenced from there:

from pinout.components.layout import Diagram
from pinout.core import Image

diagram = Diagram(800,400)

# Add an image into the diagram's 'defs'
img_src = diagram.add_def(Image("hardware.png"))

# Create x2 new image instances both referencing 'img_src'
img_01 = diagram.add(Image(img_src, x=20, y=20))
img_02 = diagram.add(Image(img_src, x=400, y=20))

Parameters

path (string) – Path to either an image file on the local file system or a URL. If using a relative path it is relative to the pinout script location.
embed (bool, optional) – Embed image in exported file, defaults to False

Coordinates stored in an Image instance can be retrieved with Image.coord(<coord_name>). On retrieval, coordinates are transformed to remain in the correct relative location on image instance regardless of the image’s position, width, height, and rotation, for example:

from pinout.components.layout import Diagram
from pinout.core import Image

diagram = Diagram(800,400)

# Create an Image instance 'img'
# Parameters match desired output and may
# differ from the image's actual dimensions
img = diagram.add(Image(
    "hardware.png",
    x=50,
    y=10,
    width=100,
    height=200,
    rotate=30
))

# Add a coordinate to 'img'
# This coordinate is measured against the original image at 1:1 scale
img.add_coord("pin_a", 110, 150)

# The transformed coordinate aligns correctly on the transformed image
pin_a = img.coord("pin_a")

By default returned coordinates include any offset that occurs when non-proportional width and height are set. By setting raw=True the coordinates are scaled purely on actual size vs. user nominated size. This is useful for documenting pin_pitch.

Parameters

name (string) – Name of coordinate
raw (bool, optional) – Return a scaled values without image offset, defaults to False

Returns

Coordinates scaled to match image scaling

Return type

tuple (x, y)