Python interface

emblematic has a Python interface that can be called from other Python scripts to programmatically generate emblems.

Installation

emblematic is distributed both via PyPI and Steffo’s Forge.

Use your favorite package manager to install it in your project.

For example, with Poetry via PyPI:

$ poetry add emblematic

Or, with pip via Steffo’s Forge:

$ pip install –index-url ‘https://forge.steffo.eu/api/packages/steffo/pypi/simple/’ emblematic

Usage

Composition

This package should usually be imported as emblematic.composition:

from emblematic.composition import compose_basic, compose_solid, compose_shadow, compose_duotone

Each of the compose_* functions correspond to a mode of the Command-line interface, except that they take as input instances of bs4.BeautifulSoup to operate on.

A very basic usage example is:

from bs4 import BeautifulSoup
from emblematic.composition import compose_basic

with open("background.svg", encoding="utf-8") as bg_file:
    with open("foreground.svg", encoding="utf-8") as fg_file:
        bg_soup = BeautifulSoup(bg_file, features="lxml-xml")
        fg_soup = BeautifulSoup(fg_file, features="lxml-xml")

final_soup = compose_basic(
    background=bg_soup,
    foreground=fg_soup,
    final_width_px=512.0,
    final_height_px=512.0,
)

final_pretty = final_soup.prettify()

with open("final.svg", encoding="utf-8") as final_file:
    final_file.write(final_pretty)

Converting to PNG

If you want to additionally convert to PNG with Inkscape, like the Command-line interface does, and assuming you have properly installed the Prerequisites, you can use subprocess similarly to this:

import subprocess

...

destination = "final.png"
width_px = int(512.0)
height_px = int(512.0)

result = subprocess.run(
    args=[
        "inkscape",
        "--pipe",
        "--export-type=png",
        f"--export-filename={destination}",
        f"--export-width={width_px}",
        f"--export-height={height_px}"
    ],
    input=svg_data.encode("utf-8"),
)
if result.returncode != 0:
    raise ChildProcessError("Conversion to PNG with Inkscape returned non-zero exit code: ", result.returncode)

API reference

Emblem composition

Composition of emblems from multiple documents, making use of various operations.

emblematic.composition.compose_basic(background: BeautifulSoup, foreground: BeautifulSoup, *, final_width_px: float, final_height_px: float) → BeautifulSoup

Create an emblem by overlaying the given foreground document on the given background document, rescaling both to the given dimensions.

Warning

This function will alter the two given documents, make sure to copy them with __copy__ if this is undesirable.

Warning

This function will not check that the inputs are valid, make sure that the given documents contain a svg tag each.

Parameters:

  • background – The background document.

  • foreground – The foreground document, most likely an icon.

  • final_width_px – The desired width of the final document.

  • final_height_px – The desired height of the final document.

Returns:

The document containing the created emblem.

emblematic.composition.compose_solid(background: BeautifulSoup, foreground: BeautifulSoup, *, foreground_fill: str, final_width_px: float, final_height_px: float) → BeautifulSoup

Like compose_basic(), but fills all paths in the foreground document with the given color.

Use-case is FontAwesome Solid icons, but should work with most others as well.

Parameters:

  • background – The background document.

  • foreground – The foreground document, most likely an icon.

  • foreground_fill – The color to fill the foreground with.

  • final_width_px – The desired width of the final document.

  • final_height_px – The desired height of the final document.

Returns:

The document containing the created emblem.

emblematic.composition.compose_shadow(background: BeautifulSoup, foreground: BeautifulSoup, *, foreground_fill: str, shadow_x_px: float, shadow_y_px: float, shadow_stddev: float, shadow_color: str, shadow_opacity: float, final_width_px: float, final_height_px: float) → BeautifulSoup

Like compose_solid(), but adds a shadow to the icon.

Warning

This function will replace any defs tag the foreground document may contain with its own.

Warning

PNG generation will not function correctly if a color with transparency is specified as shadow_color. Use shadow_opacity instead!

Parameters:

  • background – The background document.

  • foreground – The foreground document, most likely an icon.

  • foreground_fill – The color to fill the foreground with.

  • shadow_x_px – The horizontal pixel offset of the shadow.

  • shadow_y_px – The vertical pixel offset of the shadow.

  • shadow_stddev – The standard deviation of the blur.

  • shadow_color – The color to fill the shadow with.

  • shadow_opacity – The opacity of the shadow.

  • final_width_px – The desired width of the final document.

  • final_height_px – The desired height of the final document.

Returns:

The document containing the created emblem.

emblematic.composition.compose_duotone(background: BeautifulSoup, foreground: BeautifulSoup, *, primary_fill: str, secondary_fill: str, final_width_px: float, final_height_px: float) → BeautifulSoup

Like compose_basic(), but fills the path with the fa-primary id with the first color given, and the path with the fa-secondary id with the second color given.

This function will remove any defs tag the foreground document may contain.

Use-case is FontAwesome Duotone icons.

Parameters:

  • background – The background document.

  • foreground – The foreground document, most likely an icon.

  • primary_fill – The color to fill the primary part of the icon with.

  • secondary_fill – The color to fill the secondary part of the icon with.

  • final_width_px – The desired width of the final document.

  • final_height_px – The desired height of the final document.

Returns:

The document containing the created emblem.

SVG modification

Basic operations that can be performed on <svg> tags, like stretching and centering.

Except for combine(), all these methods operate in-place.

emblematic.svg.stretch_center(tag: Tag, width_pct: float = 100.0, height_pct: float = 100.0) → None

Make a SVG tag fill a portion of its parent, ignoring its original aspect ratio.

Parameters:

  • tag – The tag to edit.

  • width_pct – The width percentage to fill.

  • height_pct – The height percentage to fill.

emblematic.svg.contain_center(tag: Tag, width_pct: float = 100.0, height_pct: float = 100.0) → None

Make a SVG tag fill a portion of its parent, respecting its original aspect ratio by making it smaller than the area if necessary, then centering.

Parameters:

  • tag – The tag to edit.

  • width_pct – The width percentage to fill.

  • height_pct – The height percentage to fill.

emblematic.svg.combine(*tags: Tag, width_px: float, height_px: float) → BeautifulSoup

Create a new SVG document of the given absolute size containing all the given tags.

Parameters:

  • tags – The tags to combine.

  • width_px – The absolute width in pixels of the new document.

  • height_px – The absolute height in pixels of the new document.

Returns:

The created SVG document.

emblematic.svg.remove_defs(tag: Tag) → None

Remove all defs tags from the given SVG tag.

Parameters:

tag – The tag to edit.

emblematic.svg.create_defs(doc: BeautifulSoup, tag: Tag) → Tag

Create a defs tag in the given SVG tag.

Parameters:

  • doc – The document the tag is contained in.

  • tag – The svg tag to create defs in.

Returns:

The created defs tag.

emblematic.svg.create_dropshadow(doc: BeautifulSoup, tag: Tag, id_: str, shadow_x_px: float, shadow_y_px: float, shadow_stddev: float, shadow_color: str, shadow_opacity: float) → Tag

Create a filter tag describing a shadow with gaussian blur in the given defs tag.

Warning

Inkscape does not support transparency in feFlood[flood-color], so specifying a transparent color as shadow_color will break PNG generation.

Parameters:

  • doc – The document the tag is contained in.

  • tag – The defs tag to create filter in.

  • id – The id to give to the filter.

  • shadow_x_px – The horizontal pixel offset of the shadow.

  • shadow_y_px – The vertical pixel offset of the shadow.

  • shadow_stddev – The standard deviation of the blur.

  • shadow_color – The color of the shadow.

  • shadow_opacity – The opacity of the shadow.

Returns:

The created filter tag.

emblematic.svg.fill_all(tag: Tag, color: str) → None

Fill, with the given color, all paths in the given SVG tag.

Parameters:

  • tag – The tag to edit.

  • color – The color to fill paths with.

emblematic.svg.fill_specific(tag: Tag, class_: str, color: str) → None

Fill, with the given color, the paths with the given class in the given SVG tag.

Parameters:

  • tag – The tag to edit.

  • class – The class name to find.

  • color – The color to fill paths with.

Command-line interface definition

Arguments and options

emblematic.cli.argopts.option_background_file(f: FC) → FC
emblematic.cli.argopts.arguments_foreground_filename(f: FC) → FC
emblematic.cli.argopts.option_output_dir(f: FC) → FC
emblematic.cli.argopts.option_save_svg(f: FC) → FC
emblematic.cli.argopts.option_save_png(f: FC) → FC
emblematic.cli.argopts.option_width_px(f: FC) → FC
emblematic.cli.argopts.option_height_px(f: FC) → FC
emblematic.cli.argopts.option_foreground_color(f: FC) → FC
emblematic.cli.argopts.option_primary_color(f: FC) → FC
emblematic.cli.argopts.option_secondary_color(f: FC) → FC
emblematic.cli.argopts.option_shadow_offset_x_px(f: FC) → FC
emblematic.cli.argopts.option_shadow_offset_y_px(f: FC) → FC
emblematic.cli.argopts.option_shadow_stddev(f: FC) → FC
emblematic.cli.argopts.option_shadow_color(f: FC) → FC
emblematic.cli.argopts.option_shadow_opacity(f: FC) → FC

Commands

File detection

Module containing functions to operate on files or directories.

class emblematic.cli.files.WorkUnit(source: Path, destination_stem: Path)
classmethod find(sources: Iterable[Path], destination: Path, dir_glob: str = '**/*.svg') → set[WorkUnit]

Create a set of WorkUnit from a list of sources and a destination directory.

If a source is a directory, this function selects all files inside matching dir_glob, producing destination paths preserving the original source directory structure.

Warning

This method assumes the sources exist. Check before calling it!

Warning

This method assumes the destination exists and is a directory already. Check before calling it!

Parameters:

  • sources – An iterable of the paths to the sources to use. Sources can be both files or directories.

  • destination – Path to the destination directory.

  • dir_glob – Glob to use to find files inside directory sources.

Returns:

The resulting set of WorkUnit.

create_destination_parents()

Create the parent directories of destination_stem, if they do not already exist.

destination_svg() → Path
Returns:

destination_stem, but with the .svg file extension.

write_svg(svg_data: str) → Path

Write the given SVG document to destination_svg().

Warning

This method assumes the parent directories exist. Create them with create_destination_parents() before running it!

Parameters:

svg_data – The SVG document, in string form.

destination_png() → Path
Returns:

destination_stem, but with the .png file extension.

write_png(svg_data: str, *, width_px: int, height_px: int) → Path

Write the given SVG document as PNG to destination_png(), calling Inkscape in a subprocess to perform the conversion.

Warning

This method assumes the parent directories exist. Create them with create_destination_parents() before running it!

Parameters:

  • svg_data – The SVG document, in string form.

  • width_px – The width in pixels of the resulting image.

  • height_px – The height in pixels of the resulting image.