✨ Streamlined icon variants delivery

Credits to WikiMedia and svgrepo.com for sample icons.

This project provides is a lightweight Python utility for generating customized variants of SVG icons. It is ideal for creating the following:

• Release Channels: Unique icons for beta or alpha versions.
• Platform-Specific Branding: Tailoring icons for documentation, meetings, or CI/CD pipelines.
• Team Productivity: Any other custom visualisation for team resources.

• Style Modification: Dynamically change SVG elements using XPath-based style patching.
• Final Rasterization: Output icons in multiple formats (WebP, JPEG, and PNG) and sizes, with options for quality tuning and lossless support.
• Simplicity: A single-file Python script and configuration file that can be easily integrated into CI/CD pipelines, Git hooks, and more.

ftf-logo is a regular Python project. Project's dependencies are listed in the a project metadata file named pyproject.toml.

• Python 3.10 or higher
• Cairo 2D Library
  • (Package name may vary: cairo, libcairo2, or GTK+ Runtime for Windows)
• A PEP 621 compliant package manager (hatch, uv, pdm, and so on).

# Clone the repository
git clone https://github.com/nadvotsky/ftf-logo

# Enter the working directory
cd ftf-logo

The project includes a sample configuration at ./example/config.yaml that can be easily modified.

For a full breakdown of all configuration options, see the Configuration section below.

Finally, invoke the script and observe the results:

hatch run python src/compile.py \
  --config-file=example/config.yaml \
  --input-icon=example/inputs/logo.svg \
  --compile-to=example/outputs

The project's behavior is controlled by a single configuration file in YAML format. The following is a complete schema with detailed explanations for each setting.

Please ensure to specify the non-specific YAML tags, as it is crucial for the internal processes.

Specifies configuration the file version. Currently supported values: v1.0-amily.

This section specifies the migration data. Currently is not used and must equal to null (~).

This section defines the core transformations for icons.

• classes: An array of strings that define color variations. These will be appended to the output filenames.
• xpath_match: A key-value map where each key is a human-readable name for an element (e.g., core) and the value is the XPath expression to select that element in the SVG file.
• palette: Defines the styles to apply. The keys are the class names from classes, and the values are another map where the keys are the XPath names from xpath_match, and the values are the CSS style expressions to apply (e.g., fill:#ffffff).

This transformation embeds other icons into the input icon.

• sources: An array of paths to the SVG icons to embed.
• width and height: The size of the embedded icon. Both absolute values and ercentages are supported.
• x and y: The placement of the embedded icon. Both absolute values and ercentages are supported.

This transformation defines the final rasterization rules and output formats.

• profiles: A key-value map where each key is an output format (e.g. png) and the value is a profile for that format.

• sizes: An array of integers specifying the output sizes in pixels (e.g., [256, 512]).

• sizes: An array of integers specifying the output sizes in pixels (e.g., [256, 512]).
• quality: A lossy compression level. Must be bigger than 0 and less than or equal to 95.

• sizes: An array of integers specifying the output sizes in pixels (e.g., [256, 512]).
• quality: A lossy compression level. Must be bigger than 0 and less than or equal to 100.
• lossless: A boolean flag that controls lossless compression.

This utility uses widely-adopted and popular Unix command-line flags syntax. See the Advanced Bash-Scripting Guide for a quick intro to this concept.

• Description: Path to the input source SVG icon.
• Required: Yes.

Description: Path to the configuration file. Required: Yes.

Description: Sets the destination folder for compiled files. Required: Yes.

Description: Specifies the logging level. Allowed Values: DEBUG, INFO, WARNING, ERROR, CRITICAL. Required: No (default is ERROR).

Description: Path to a file for an additional log output. Required: No (by default, no log file is used).

Description: Disables specific runtime features. Required: No (default is to enable all features).

The following features can be disabled:

• TYPECHECK: Disables runtime data validation for configuration and input.
• FAILIFNOFLAWLESSTYPECHECK: Prevents validation warnings from becoming fatal errors.
• FAILIFSOURCENOTEXISTS: Disables the check for the output directory.

Here is an example of how to integrate ftf-logo into a Bitbucket pipeline.

image: python:slim

definitions:
  caches:
    hatch-cache:
      key:
        files:
          - pyproject.toml
      path: ~/.local/share/hatch

pipelines:
  default:
    - step:
        name: Build icons
        caches:
          - hatch-cache
        script:
          # Install Cairo and create the output directory.
          - apt-get update && DEBIAN_FRONTEND=noninteractive apt-get -qq install libcairo2
          - mkdir -p example/outputs

          # Install dependencies and run the script with Hatch.
          - pip install --prefer-binary --progress-bar=off hatch
          - >-
              hatch -v --no-interactive run python src/compile.py
              --config-file=example/config.yaml
              --input-icon=example/inputs/logo.svg
              --log-level=DEBUG
              --compile-to=example/outputs

          # Create and publish the release archive.
          - (cd example/outputs && tar cvf "outputs-${BITBUCKET_COMMIT::7}.tar.gz" *.*)
          - pipe: atlassian/bitbucket-upload-file:0.6.0
            variables:
              BITBUCKET_USERNAME: $BITBUCKET_USERNAME
              BITBUCKET_APP_PASSWORD: $BITBUCKET_APP_PASSWORD
              FILENAME: "example/outputs/outputs-*.tar.gz"

This project is released under the MIT license.

Thanks for using ftf-logo! A big thank you to the developers of these fantastic projects:

• Python Programming Language
• Hatch Python Package Manager
• Cairo 2D Graphics Library
• CairoSVG Python Library
• Pillow Image Processing Library
• lxml XML and HTML Python Library
• pyYAML Python Library
• Click CLI Python Library