eulumdat-plot 0.0.1__tar.gz → 1.0.0__tar.gz

eulumdat_plot-1.0.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: eulumdat-plot
+Version: 1.0.0
+Summary: Photometric polar diagram generator for EULUMDAT (.ldt) files — extension to eulumdat-py
+Author: 123VincentB
+License: MIT
+Project-URL: Homepage, https://github.com/123VincentB/eulumdat-plot
+Project-URL: Repository, https://github.com/123VincentB/eulumdat-plot
+Project-URL: Issues, https://github.com/123VincentB/eulumdat-plot/issues
+Project-URL: Changelog, https://github.com/123VincentB/eulumdat-plot/blob/main/CHANGELOG.md
+Keywords: eulumdat,ldt,photometry,lighting,luminaire,polar,candela,diagram,svg,lumtopic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Manufacturing
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: eulumdat-py>=1.0.0
+Requires-Dist: numpy>=1.21
+Requires-Dist: svgwrite>=1.4
+Provides-Extra: export
+Requires-Dist: vl-convert-python>=1.6; extra == "export"
+Requires-Dist: Pillow>=9.0; extra == "export"
+Provides-Extra: cubic
+Requires-Dist: scipy>=1.7; extra == "cubic"
+Provides-Extra: full
+Requires-Dist: eulumdat-plot[export]; extra == "full"
+Requires-Dist: eulumdat-plot[cubic]; extra == "full"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: eulumdat-plot[full]; extra == "dev"
+
+# eulumdat-plot
+
+Photometric polar diagram generator for EULUMDAT (`.ldt`) files —
+designed for **product datasheets and publication-ready documents**.
+
+Reads a `.ldt` file and produces a **Lumtopic-style SVG**: a square image
+with a top banner and a polar candela distribution diagram showing the
+C0/C180 (solid) and C90/C270 (dotted) curves, scaled to fill the plot area.
+
+> **For scientific / interactive plots** (matplotlib, axis labels, legends),
+> see the
+> [eulumdat-py examples](https://github.com/123VincentB/eulumdat-py/blob/main/examples/02_polar_diagram.md).
+
+Part of the [`eulumdat-*`](https://github.com/123VincentB) ecosystem, built
+on top of [`eulumdat-py`](https://pypi.org/project/eulumdat-py/).
+
+---
+
+![Photometric diagram example](docs/img/sample_01.svg)
+
+---
+
+## Features
+
+- Reads any EULUMDAT file — all symmetry types (ISYM 0–4) handled by `eulumdat-py`
+- Generates a **publication-ready SVG** polar diagram (Lumtopic style)
+- Dynamic radial scale (3–6 concentric circles, round values)
+- Dominant-hemisphere detection for automatic scale label placement
+- Proportional scaling via `Layout.for_size(n)` — one parameter controls everything
+- Optional I(γ) interpolation (linear or cubic spline) for smooth curves
+- Optional raster export to **PNG** and **JPEG** (cross-platform, no native DLL)
+- Debug mode for visual validation of C-plane assignment
+
+## Installation
+
+Core package (SVG generation only):
+
+```bash
+pip install eulumdat-plot
+```
+
+With raster export (PNG / JPEG):
+
+```bash
+pip install "eulumdat-plot[export]"
+```
+
+With cubic spline interpolation:
+
+```bash
+pip install "eulumdat-plot[cubic]"
+```
+
+Everything:
+
+```bash
+pip install "eulumdat-plot[full]"
+```
+
+## Quick start
+
+```python
+from eulumdat_plot import plot_ldt
+
+# Generate an SVG next to the source file
+svg = plot_ldt("luminaire.ldt")
+
+# With a distribution code in the banner centre
+svg = plot_ldt("luminaire.ldt", code="D53")
+```
+
+## Scaling
+
+All visual parameters (stroke widths, font sizes, margins) scale
+proportionally from the 1181 px reference with a single call:
+
+```python
+from eulumdat_plot import plot_ldt, Layout
+
+svg = plot_ldt("luminaire.ldt", layout=Layout.for_size(600))
+```
+
+## Raster export
+
+```python
+from eulumdat_plot import plot_ldt, Layout
+from eulumdat_plot.export import svg_to_png, svg_to_jpg
+
+svg = plot_ldt("luminaire.ldt", layout=Layout.for_size(1181))
+png = svg_to_png(svg, size_px=600)
+jpg = svg_to_jpg(svg, size_px=600, quality=95)
+```
+
+The export size is independent of the SVG canvas size.
+
+## API reference
+
+### `plot_ldt()`
+
+```python
+def plot_ldt(
+    ldt_path: str | Path,
+    svg_path: str | Path | None = None,
+    *,
+    code: str = "",
+    layout: Layout | None = None,
+    interpolate: bool = True,
+    interp_step_deg: float = 1.0,
+    interp_method: str = "linear",
+    debug: bool = False,
+) -> Path
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `ldt_path` | — | Source `.ldt` file |
+| `svg_path` | same name, `.svg` | Output SVG path |
+| `code` | `""` | Distribution code shown in the banner centre |
+| `layout` | `Layout()` | Visual parameters |
+| `interpolate` | `True` | Resample I(γ) before plotting |
+| `interp_step_deg` | `1.0` | Angular step for resampling (degrees) |
+| `interp_method` | `"linear"` | `"linear"` or `"cubic"` (requires scipy) |
+| `debug` | `False` | Colour-code C-planes for visual validation |
+
+### `Layout.for_size()`
+
+```python
+Layout.for_size(size_px: int) -> Layout
+```
+
+Creates a `Layout` with all dimensions scaled proportionally from the
+1181 px reference. `Layout.for_size(1181)` is identical to `Layout()`.
+
+### `svg_to_png()` / `svg_to_jpg()`
+
+```python
+svg_to_png(svg_path, png_path=None, *, size_px=1181, background="#FFFFFF") -> Path
+svg_to_jpg(svg_path, jpg_path=None, *, size_px=1181, background="#FFFFFF", quality=95) -> Path
+```
+
+Requires `pip install "eulumdat-plot[export]"`.
+
+## Examples
+
+| File | Description |
+|---|---|
+| [`examples/01_basic_usage.md`](examples/01_basic_usage.md) | Generate an SVG from a `.ldt` file |
+| [`examples/02_resize_and_export.md`](examples/02_resize_and_export.md) | Scaling, raster export, batch processing |
+
+## Project structure
+
+```
+eulumdat-plot/
+├── data/
+│   ├── input/          # sample .ldt files (ISYM 0–4)
+│   └── output/         # generated SVG / PNG / JPEG
+├── docs/
+│   └── img/
+│       └── sample_01.svg
+├── examples/
+│   ├── 01_basic_usage.md
+│   └── 02_resize_and_export.md
+├── src/
+│   └── eulumdat_plot/
+│       ├── __init__.py
+│       ├── plot.py     # public API — LDT → SVG pipeline
+│       ├── renderer.py # SVG renderer + Layout dataclass
+│       └── export.py   # raster export (PNG / JPEG)
+├── tests/
+│   ├── test_smoke.py   # 46 real LDT files, all ISYM types
+│   └── test_scaling.py # Layout.for_size() proportionality
+├── pyproject.toml
+├── CHANGELOG.md
+└── README.md
+```
+
+## EULUMDAT ecosystem
+
+| Package | Status | Description |
+|---|---|---|
+| [`eulumdat-py`](https://pypi.org/project/eulumdat-py/) | v0.1.4 | Read / write EULUMDAT files |
+| [`eulumdat-symmetry`](https://pypi.org/project/eulumdat-symmetry/) | v1.0.0 | Symmetrise EULUMDAT files |
+| `eulumdat-plot` | v1.0.0 | Photometric polar diagram — **this package** |
+| `eulumdat-luminance` | planned | Luminance table cd/m² (γ 55°–85°) |
+| `eulumdat-ugr` | planned | UGR calculation (CIE 117, CIE 190) |
+
+## Requirements
+
+- Python ≥ 3.9
+- `eulumdat-py` ≥ 1.0.0
+- `numpy` ≥ 1.21
+- `svgwrite` ≥ 1.4
+- *(optional)* `vl-convert-python` ≥ 1.6 + `Pillow` ≥ 9.0 — raster export
+- *(optional)* `scipy` ≥ 1.7 — cubic spline interpolation
+
+## License
+
+MIT — © 2024 [123VincentB](https://github.com/123VincentB)

eulumdat_plot-1.0.0/README.md

@@ -0,0 +1,198 @@
+# eulumdat-plot
+
+Photometric polar diagram generator for EULUMDAT (`.ldt`) files —
+designed for **product datasheets and publication-ready documents**.
+
+Reads a `.ldt` file and produces a **Lumtopic-style SVG**: a square image
+with a top banner and a polar candela distribution diagram showing the
+C0/C180 (solid) and C90/C270 (dotted) curves, scaled to fill the plot area.
+
+> **For scientific / interactive plots** (matplotlib, axis labels, legends),
+> see the
+> [eulumdat-py examples](https://github.com/123VincentB/eulumdat-py/blob/main/examples/02_polar_diagram.md).
+
+Part of the [`eulumdat-*`](https://github.com/123VincentB) ecosystem, built
+on top of [`eulumdat-py`](https://pypi.org/project/eulumdat-py/).
+
+---
+
+![Photometric diagram example](docs/img/sample_01.svg)
+
+---
+
+## Features
+
+- Reads any EULUMDAT file — all symmetry types (ISYM 0–4) handled by `eulumdat-py`
+- Generates a **publication-ready SVG** polar diagram (Lumtopic style)
+- Dynamic radial scale (3–6 concentric circles, round values)
+- Dominant-hemisphere detection for automatic scale label placement
+- Proportional scaling via `Layout.for_size(n)` — one parameter controls everything
+- Optional I(γ) interpolation (linear or cubic spline) for smooth curves
+- Optional raster export to **PNG** and **JPEG** (cross-platform, no native DLL)
+- Debug mode for visual validation of C-plane assignment
+
+## Installation
+
+Core package (SVG generation only):
+
+```bash
+pip install eulumdat-plot
+```
+
+With raster export (PNG / JPEG):
+
+```bash
+pip install "eulumdat-plot[export]"
+```
+
+With cubic spline interpolation:
+
+```bash
+pip install "eulumdat-plot[cubic]"
+```
+
+Everything:
+
+```bash
+pip install "eulumdat-plot[full]"
+```
+
+## Quick start
+
+```python
+from eulumdat_plot import plot_ldt
+
+# Generate an SVG next to the source file
+svg = plot_ldt("luminaire.ldt")
+
+# With a distribution code in the banner centre
+svg = plot_ldt("luminaire.ldt", code="D53")
+```
+
+## Scaling
+
+All visual parameters (stroke widths, font sizes, margins) scale
+proportionally from the 1181 px reference with a single call:
+
+```python
+from eulumdat_plot import plot_ldt, Layout
+
+svg = plot_ldt("luminaire.ldt", layout=Layout.for_size(600))
+```
+
+## Raster export
+
+```python
+from eulumdat_plot import plot_ldt, Layout
+from eulumdat_plot.export import svg_to_png, svg_to_jpg
+
+svg = plot_ldt("luminaire.ldt", layout=Layout.for_size(1181))
+png = svg_to_png(svg, size_px=600)
+jpg = svg_to_jpg(svg, size_px=600, quality=95)
+```
+
+The export size is independent of the SVG canvas size.
+
+## API reference
+
+### `plot_ldt()`
+
+```python
+def plot_ldt(
+    ldt_path: str | Path,
+    svg_path: str | Path | None = None,
+    *,
+    code: str = "",
+    layout: Layout | None = None,
+    interpolate: bool = True,
+    interp_step_deg: float = 1.0,
+    interp_method: str = "linear",
+    debug: bool = False,
+) -> Path
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `ldt_path` | — | Source `.ldt` file |
+| `svg_path` | same name, `.svg` | Output SVG path |
+| `code` | `""` | Distribution code shown in the banner centre |
+| `layout` | `Layout()` | Visual parameters |
+| `interpolate` | `True` | Resample I(γ) before plotting |
+| `interp_step_deg` | `1.0` | Angular step for resampling (degrees) |
+| `interp_method` | `"linear"` | `"linear"` or `"cubic"` (requires scipy) |
+| `debug` | `False` | Colour-code C-planes for visual validation |
+
+### `Layout.for_size()`
+
+```python
+Layout.for_size(size_px: int) -> Layout
+```
+
+Creates a `Layout` with all dimensions scaled proportionally from the
+1181 px reference. `Layout.for_size(1181)` is identical to `Layout()`.
+
+### `svg_to_png()` / `svg_to_jpg()`
+
+```python
+svg_to_png(svg_path, png_path=None, *, size_px=1181, background="#FFFFFF") -> Path
+svg_to_jpg(svg_path, jpg_path=None, *, size_px=1181, background="#FFFFFF", quality=95) -> Path
+```
+
+Requires `pip install "eulumdat-plot[export]"`.
+
+## Examples
+
+| File | Description |
+|---|---|
+| [`examples/01_basic_usage.md`](examples/01_basic_usage.md) | Generate an SVG from a `.ldt` file |
+| [`examples/02_resize_and_export.md`](examples/02_resize_and_export.md) | Scaling, raster export, batch processing |
+
+## Project structure
+
+```
+eulumdat-plot/
+├── data/
+│   ├── input/          # sample .ldt files (ISYM 0–4)
+│   └── output/         # generated SVG / PNG / JPEG
+├── docs/
+│   └── img/
+│       └── sample_01.svg
+├── examples/
+│   ├── 01_basic_usage.md
+│   └── 02_resize_and_export.md
+├── src/
+│   └── eulumdat_plot/
+│       ├── __init__.py
+│       ├── plot.py     # public API — LDT → SVG pipeline
+│       ├── renderer.py # SVG renderer + Layout dataclass
+│       └── export.py   # raster export (PNG / JPEG)
+├── tests/
+│   ├── test_smoke.py   # 46 real LDT files, all ISYM types
+│   └── test_scaling.py # Layout.for_size() proportionality
+├── pyproject.toml
+├── CHANGELOG.md
+└── README.md
+```
+
+## EULUMDAT ecosystem
+
+| Package | Status | Description |
+|---|---|---|
+| [`eulumdat-py`](https://pypi.org/project/eulumdat-py/) | v0.1.4 | Read / write EULUMDAT files |
+| [`eulumdat-symmetry`](https://pypi.org/project/eulumdat-symmetry/) | v1.0.0 | Symmetrise EULUMDAT files |
+| `eulumdat-plot` | v1.0.0 | Photometric polar diagram — **this package** |
+| `eulumdat-luminance` | planned | Luminance table cd/m² (γ 55°–85°) |
+| `eulumdat-ugr` | planned | UGR calculation (CIE 117, CIE 190) |
+
+## Requirements
+
+- Python ≥ 3.9
+- `eulumdat-py` ≥ 1.0.0
+- `numpy` ≥ 1.21
+- `svgwrite` ≥ 1.4
+- *(optional)* `vl-convert-python` ≥ 1.6 + `Pillow` ≥ 9.0 — raster export
+- *(optional)* `scipy` ≥ 1.7 — cubic spline interpolation
+
+## License
+
+MIT — © 2024 [123VincentB](https://github.com/123VincentB)

eulumdat_plot-1.0.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "eulumdat-plot"
+version = "1.0.0"
+description = "Photometric polar diagram generator for EULUMDAT (.ldt) files — extension to eulumdat-py"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "123VincentB" }]
+requires-python = ">=3.9"
+
+dependencies = [
+    "eulumdat-py >= 1.0.0",
+    "numpy >= 1.21",
+    "svgwrite >= 1.4",
+]
+
+keywords = [
+    "eulumdat", "ldt", "photometry", "lighting", "luminaire",
+    "polar", "candela", "diagram", "svg", "lumtopic",
+]
+
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Manufacturing",
+    "Topic :: Scientific/Engineering :: Physics",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.optional-dependencies]
+# Raster export (SVG → PNG / JPEG)
+export = [
+    "vl-convert-python >= 1.6",
+    "Pillow >= 9.0",
+]
+# Smooth curve interpolation
+cubic = [
+    "scipy >= 1.7",
+]
+# Everything
+full = [
+    "eulumdat-plot[export]",
+    "eulumdat-plot[cubic]",
+]
+# Development tools
+dev = [
+    "build",
+    "twine",
+    "pytest >= 7.0",
+    "eulumdat-plot[full]",
+]
+
+[project.urls]
+Homepage    = "https://github.com/123VincentB/eulumdat-plot"
+Repository  = "https://github.com/123VincentB/eulumdat-plot"
+Issues      = "https://github.com/123VincentB/eulumdat-plot/issues"
+Changelog   = "https://github.com/123VincentB/eulumdat-plot/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+# Add src/ to sys.path so pytest finds eulumdat_plot without editable install.
+pythonpath = ["src"]
+testpaths  = ["tests"]

eulumdat_plot-1.0.0/src/eulumdat_plot/__init__.py

@@ -0,0 +1,50 @@
+"""
+eulumdat-plot — Photometric polar diagram generator for EULUMDAT (.ldt) files.
+
+This package is an extension of ``eulumdat-py`` (``pyldt``).
+It reads a ``.ldt`` file and generates a photometric polar diagram in the
+style of the Lumtopic software: a square SVG image with a top banner
+("LED" / distribution code / "cd / klm") and a polar plot showing the
+C0/C180 distribution (solid curve) and C90/C270 distribution (dotted curve).
+
+Quick start
+-----------
+::
+
+    from eulumdat_plot import plot_ldt
+
+    # Minimal — outputs "luminaire.svg" next to the source file.
+    svg = plot_ldt("luminaire.ldt")
+
+    # With distribution code and custom canvas size.
+    from eulumdat_plot import Layout
+    layout = Layout(width=800, height=800)
+    svg = plot_ldt("luminaire.ldt", code="D53", layout=layout)
+
+    # Raster export (requires the ``[export]`` optional dependency).
+    from eulumdat_plot.export import svg_to_png, svg_to_jpg
+    png = svg_to_png(svg)
+    jpg = svg_to_jpg(svg)
+
+Public API
+----------
+:func:`plot_ldt`
+    Main entry point: LDT file → SVG diagram.
+:class:`Layout`
+    Dataclass holding all visual parameters (sizes, stroke widths, fonts…).
+:func:`make_svg`
+    Low-level renderer: pre-computed NAT curves → SVG.
+    Useful if you need to build curves yourself and bypass the LDT pipeline.
+:func:`polar_to_nat`
+    Convert polar ``(r, θ)`` to NAT ``(x, y)`` Cartesian coordinates.
+"""
+
+from .plot import plot_ldt
+from .renderer import Layout, make_svg, polar_to_nat
+
+__all__ = [
+    "plot_ldt",
+    "Layout",
+    "make_svg",
+    "polar_to_nat",
+]

eulumdat_plot-1.0.0/src/eulumdat_plot/export.py

@@ -0,0 +1,145 @@
+"""
+export.py — Raster export of photometric SVG diagrams.
+
+Converts SVG files produced by :func:`plot.plot_ldt` (or any compatible
+SVG) to PNG or JPEG.
+
+Dependencies
+------------
+``vl-convert-python``
+    Pure-Python package embedding a compiled Rust/resvg SVG renderer.
+    No native library (DLL/SO) required — the renderer is bundled in the
+    wheel.  Cross-platform: Windows, Linux, macOS.
+    Install with the optional extra::
+
+        pip install "eulumdat-plot[export]"
+
+``Pillow``
+    Used for pixel-exact resizing and JPEG compression.
+    Also installed via ``[export]``.
+"""
+
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+
+def _check_deps() -> None:
+    """Raise a clear ImportError if vl-convert-python or Pillow are missing."""
+    missing = []
+    for pkg, pip_name in [("vl_convert", "vl-convert-python"), ("PIL", "Pillow")]:
+        try:
+            __import__(pkg)
+        except ImportError:
+            missing.append(pip_name)
+    if missing:
+        raise ImportError(
+            f"Missing package(s) for raster export: {', '.join(missing)}\n"
+            "Install with:  pip install 'eulumdat-plot[export]'"
+        )
+
+
+def _svg_to_pil(svg_path: Path, size_px: int, background: str):
+    """
+    Convert an SVG file to a square Pillow Image of exactly *size_px* pixels.
+
+    Uses ``vl_convert`` (resvg, compiled Rust, no native DLL) for rendering,
+    then ``Pillow`` for pixel-exact resizing and background compositing.
+
+    Parameters
+    ----------
+    svg_path :   Path to the source SVG file.
+    size_px :    Target output size in pixels (square).
+    background : Background colour as a CSS hex string (e.g. ``"#FFFFFF"``).
+
+    Returns
+    -------
+    PIL.Image.Image in RGB mode, size (size_px, size_px).
+    """
+    _check_deps()
+
+    import vl_convert as vlc
+    from PIL import Image
+
+    svg_content = svg_path.read_text(encoding="utf-8")
+
+    # Read the SVG canvas size from the file to compute the scale factor.
+    # Layout always writes width="N" height="N" as integers.
+    native_size = size_px   # fallback if parsing fails
+    import re
+    m = re.search(r'<svg[^>]+width="(\d+)"', svg_content)
+    if m:
+        native_size = int(m.group(1))
+
+    scale = size_px / native_size
+    png_bytes = vlc.svg_to_png(svg_content, scale=scale)
+
+    img = Image.open(io.BytesIO(png_bytes)).convert("RGBA")
+
+    # Resize to exactly size_px × size_px (float scale may be off by 1 px).
+    if img.size != (size_px, size_px):
+        img = img.resize((size_px, size_px), Image.LANCZOS)
+
+    # Composite over solid background.
+    bg = Image.new("RGBA", (size_px, size_px), background)
+    bg.paste(img, mask=img)
+    return bg.convert("RGB")
+
+
+def svg_to_png(
+    svg_path: str | Path,
+    png_path: str | Path | None = None,
+    *,
+    size_px: int = 1181,
+    background: str = "#FFFFFF",
+) -> Path:
+    """
+    Convert an SVG file to PNG.
+
+    Parameters
+    ----------
+    svg_path :   Path to the source SVG file.
+    png_path :   Destination path.  Defaults to svg_path with .png extension.
+    size_px :    Output width and height in pixels (square output).
+    background : Background fill colour as a CSS hex string. Default: #FFFFFF.
+
+    Returns
+    -------
+    Absolute path to the generated PNG file.
+    """
+    svg_path = Path(svg_path)
+    png_path = Path(png_path) if png_path is not None else svg_path.with_suffix(".png")
+    img = _svg_to_pil(svg_path, size_px, background)
+    img.save(png_path, "PNG", optimize=True)
+    return png_path.resolve()
+
+
+def svg_to_jpg(
+    svg_path: str | Path,
+    jpg_path: str | Path | None = None,
+    *,
+    size_px: int = 1181,
+    background: str = "#FFFFFF",
+    quality: int = 95,
+) -> Path:
+    """
+    Convert an SVG file to JPEG.
+
+    Parameters
+    ----------
+    svg_path :   Path to the source SVG file.
+    jpg_path :   Destination path.  Defaults to svg_path with .jpg extension.
+    size_px :    Output width and height in pixels (square output).
+    background : Background fill colour (CSS hex). Default: #FFFFFF.
+    quality :    JPEG compression quality (1-100). Default: 95.
+
+    Returns
+    -------
+    Absolute path to the generated JPEG file.
+    """
+    svg_path = Path(svg_path)
+    jpg_path = Path(jpg_path) if jpg_path is not None else svg_path.with_suffix(".jpg")
+    img = _svg_to_pil(svg_path, size_px, background)
+    img.save(jpg_path, "JPEG", quality=quality, optimize=True)
+    return jpg_path.resolve()