streamlit-drawable-konva 0.1.0__tar.gz

streamlit_drawable_konva-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Streamlit Drawable Konva Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

streamlit_drawable_konva-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include streamlit_drawable_konva/frontend/build *
+include streamlit_drawable_konva/pyproject.toml

streamlit_drawable_konva-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: streamlit-drawable-konva
+Version: 0.1.0
+Summary: Streamlit drawable canvas component using Konva.js (Components v2)
+Author-email: George Siogkas <gsiogkas@cvrlab.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gsiogkas/streamlit-drawable-konva
+Project-URL: Documentation, https://github.com/gsiogkas/streamlit-drawable-konva#readme
+Project-URL: Repository, https://github.com/gsiogkas/streamlit-drawable-konva
+Project-URL: Issues, https://github.com/gsiogkas/streamlit-drawable-konva/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: streamlit>=1.51
+Requires-Dist: numpy
+Requires-Dist: pillow
+Provides-Extra: demo
+Requires-Dist: pandas; extra == "demo"
+Provides-Extra: devel
+Requires-Dist: wheel; extra == "devel"
+Requires-Dist: pandas; extra == "devel"
+Dynamic: license-file
+
+# Streamlit Drawable Konva
+
+Streamlit custom component (Components **v2**) that provides a sketching canvas
+using [Konva.js](https://konvajs.org/) / `react-konva`.
+
+The public Python API is intentionally compatible with
+[`streamlit-drawable-canvas-fix`](https://pypi.org/project/streamlit-drawable-canvas-fix/)
+(`st_canvas` → `CanvasResult(image_data, json_data)`). Object JSON uses
+Konva-oriented fields (`x`/`y`/`points`/…), not Fabric.js schemas.
+
+## Features
+
+- Freehand, line, rect, circle, point, polygon drawing
+- Transform mode (move / scale / rotate); double-click to delete
+- Background color or image
+- Realtime or on-demand updates to Streamlit
+- Undo / redo / clear toolbar
+- Returns RGBA `image_data` and scene `json_data`
+
+## Why Konva.js (vs Fabric.js)?
+
+Konva is not universally “better” than Fabric — both are mature 2D canvas
+libraries. For **this** Streamlit component, Konva is the better fit.
+
+| Concern | Konva | Fabric |
+| --- | --- | --- |
+| React integration | First-class via `react-konva` (declarative scene tree) | Imperative `fabric.Canvas`; React wrappers are thinner / more brittle |
+| Mental model | Stage → Layer → Shape (clear export boundaries) | Single canvas object model; background vs drawing export needs extra care |
+| Bundle / focus | Leaner, scene-graph oriented | Heavier; strong textile/image-editing heritage |
+| Transforms | Built-in `Transformer` for select / scale / rotate | Excellent selection UX; historically the gold standard for editors |
+| Ecosystem | Strong for interactive UIs and annotation tools | Huge installed base; many Fabric JSON examples in the wild |
+
+**Why we chose Konva here**
+
+1. **React + Streamlit Components v2** — the official CCv2 React template maps
+   cleanly onto `react-konva`. Drawing state stays in React; updates go out via
+   `setStateValue` without fighting an imperative canvas singleton.
+2. **Layered export** — background images can live on a non-exported layer while
+   strokes/shapes export cleanly to `image_data`, matching the upstream
+   “background is not round-tripped” behavior with less glue code.
+3. **Maintainability** — freerdraw / shapes / polygon / transform are ordinary
+   React event handlers and Konva nodes, which is easier to evolve next to a
+   modern Vite + TypeScript frontend than a Fabric-centric CRA-era stack.
+4. **Performance for annotation UIs** — Konva’s layer/stage model scales well for
+   ROI / sketching workloads typical in Streamlit apps.
+
+**When Fabric may still win**
+
+- You need **byte-compatible Fabric JSON** (existing pipelines, demos, or
+  tutorials that assume `left`/`top`/`path` Fabric schemas).
+- You want Fabric’s mature free-transform / skew / complex text editing out of
+  the box without reimplementing edge cases.
+
+This package keeps a **compatible Python API** (`st_canvas` → `CanvasResult`) so
+apps can migrate from `streamlit-drawable-canvas-fix`, while accepting that
+`json_data` is Konva-oriented rather than a Fabric dump.
+
+## Install (uv)
+
+```bash
+uv sync
+```
+
+Build the frontend once (required before first Streamlit run):
+
+```bash
+cd streamlit_drawable_konva/frontend
+npm install
+npm run build
+cd ../../
+```
+
+Editable install is handled by `uv sync` via the local `pyproject.toml`.
+
+## Demo
+
+```bash
+uv run streamlit run app.py
+```
+
+## Development
+
+CCv2 watches a production-style build into `frontend/build` (no separate webpack
+dev server URL). Use two terminals:
+
+**Terminal A — frontend watch build**
+
+```bash
+cd streamlit_drawable_konva/frontend
+npm install
+npm run dev
+```
+
+**Terminal B — Streamlit**
+
+```bash
+uv sync
+uv run streamlit run app.py
+```
+
+Refresh the browser after frontend rebuilds.
+
+## API
+
+```python
+from streamlit_drawable_konva import st_canvas
+
+result = st_canvas(
+    fill_color="rgba(255, 165, 0, 0.3)",
+    stroke_width=3,
+    stroke_color="#000000",
+    background_color="#eee",
+    background_image=None,
+    update_streamlit=True,
+    height=400,
+    width=600,
+    drawing_mode="freedraw",  # freedraw|line|rect|circle|point|polygon|transform
+    initial_drawing=None,
+    display_toolbar=True,
+    point_display_radius=3,
+    key="canvas",
+)
+
+# result.image_data -> np.ndarray | None
+# result.json_data  -> dict | None
+```
+
+### Polygon controls
+
+- Left-click: add point
+- Right-click: close polygon
+- Double-click: remove latest point
+
+### Transform controls
+
+- Click object to select
+- Drag / resize / rotate with the transformer
+- Double-click selected object to delete
+
+## Packaging notes
+
+- Registered as `streamlit-drawable-konva.st_canvas` via the in-package
+  `streamlit_drawable_konva/pyproject.toml` manifest (`asset_dir = frontend/build`).
+- Requires Streamlit `>= 1.51` (Components v2).
+- Frontend toolchain targets Node `>= 18` (Vite 5).
+
+## Publishing (GitHub / PyPI / Streamlit Cloud / gallery)
+
+Step-by-step instructions: [`PUBLISHING.md`](PUBLISHING.md).
+
+Order: push to GitHub → publish to PyPI → deploy `app.py` on Community Cloud →
+submit [`gallery/streamlit-drawable-konva.json`](gallery/streamlit-drawable-konva.json)
+as a PR to [streamlit/gallery](https://github.com/streamlit/gallery/tree/main/components/registry).
+
+## License
+
+MIT

streamlit_drawable_konva-0.1.0/README.md

@@ -0,0 +1,157 @@
+# Streamlit Drawable Konva
+
+Streamlit custom component (Components **v2**) that provides a sketching canvas
+using [Konva.js](https://konvajs.org/) / `react-konva`.
+
+The public Python API is intentionally compatible with
+[`streamlit-drawable-canvas-fix`](https://pypi.org/project/streamlit-drawable-canvas-fix/)
+(`st_canvas` → `CanvasResult(image_data, json_data)`). Object JSON uses
+Konva-oriented fields (`x`/`y`/`points`/…), not Fabric.js schemas.
+
+## Features
+
+- Freehand, line, rect, circle, point, polygon drawing
+- Transform mode (move / scale / rotate); double-click to delete
+- Background color or image
+- Realtime or on-demand updates to Streamlit
+- Undo / redo / clear toolbar
+- Returns RGBA `image_data` and scene `json_data`
+
+## Why Konva.js (vs Fabric.js)?
+
+Konva is not universally “better” than Fabric — both are mature 2D canvas
+libraries. For **this** Streamlit component, Konva is the better fit.
+
+| Concern | Konva | Fabric |
+| --- | --- | --- |
+| React integration | First-class via `react-konva` (declarative scene tree) | Imperative `fabric.Canvas`; React wrappers are thinner / more brittle |
+| Mental model | Stage → Layer → Shape (clear export boundaries) | Single canvas object model; background vs drawing export needs extra care |
+| Bundle / focus | Leaner, scene-graph oriented | Heavier; strong textile/image-editing heritage |
+| Transforms | Built-in `Transformer` for select / scale / rotate | Excellent selection UX; historically the gold standard for editors |
+| Ecosystem | Strong for interactive UIs and annotation tools | Huge installed base; many Fabric JSON examples in the wild |
+
+**Why we chose Konva here**
+
+1. **React + Streamlit Components v2** — the official CCv2 React template maps
+   cleanly onto `react-konva`. Drawing state stays in React; updates go out via
+   `setStateValue` without fighting an imperative canvas singleton.
+2. **Layered export** — background images can live on a non-exported layer while
+   strokes/shapes export cleanly to `image_data`, matching the upstream
+   “background is not round-tripped” behavior with less glue code.
+3. **Maintainability** — freerdraw / shapes / polygon / transform are ordinary
+   React event handlers and Konva nodes, which is easier to evolve next to a
+   modern Vite + TypeScript frontend than a Fabric-centric CRA-era stack.
+4. **Performance for annotation UIs** — Konva’s layer/stage model scales well for
+   ROI / sketching workloads typical in Streamlit apps.
+
+**When Fabric may still win**
+
+- You need **byte-compatible Fabric JSON** (existing pipelines, demos, or
+  tutorials that assume `left`/`top`/`path` Fabric schemas).
+- You want Fabric’s mature free-transform / skew / complex text editing out of
+  the box without reimplementing edge cases.
+
+This package keeps a **compatible Python API** (`st_canvas` → `CanvasResult`) so
+apps can migrate from `streamlit-drawable-canvas-fix`, while accepting that
+`json_data` is Konva-oriented rather than a Fabric dump.
+
+## Install (uv)
+
+```bash
+uv sync
+```
+
+Build the frontend once (required before first Streamlit run):
+
+```bash
+cd streamlit_drawable_konva/frontend
+npm install
+npm run build
+cd ../../
+```
+
+Editable install is handled by `uv sync` via the local `pyproject.toml`.
+
+## Demo
+
+```bash
+uv run streamlit run app.py
+```
+
+## Development
+
+CCv2 watches a production-style build into `frontend/build` (no separate webpack
+dev server URL). Use two terminals:
+
+**Terminal A — frontend watch build**
+
+```bash
+cd streamlit_drawable_konva/frontend
+npm install
+npm run dev
+```
+
+**Terminal B — Streamlit**
+
+```bash
+uv sync
+uv run streamlit run app.py
+```
+
+Refresh the browser after frontend rebuilds.
+
+## API
+
+```python
+from streamlit_drawable_konva import st_canvas
+
+result = st_canvas(
+    fill_color="rgba(255, 165, 0, 0.3)",
+    stroke_width=3,
+    stroke_color="#000000",
+    background_color="#eee",
+    background_image=None,
+    update_streamlit=True,
+    height=400,
+    width=600,
+    drawing_mode="freedraw",  # freedraw|line|rect|circle|point|polygon|transform
+    initial_drawing=None,
+    display_toolbar=True,
+    point_display_radius=3,
+    key="canvas",
+)
+
+# result.image_data -> np.ndarray | None
+# result.json_data  -> dict | None
+```
+
+### Polygon controls
+
+- Left-click: add point
+- Right-click: close polygon
+- Double-click: remove latest point
+
+### Transform controls
+
+- Click object to select
+- Drag / resize / rotate with the transformer
+- Double-click selected object to delete
+
+## Packaging notes
+
+- Registered as `streamlit-drawable-konva.st_canvas` via the in-package
+  `streamlit_drawable_konva/pyproject.toml` manifest (`asset_dir = frontend/build`).
+- Requires Streamlit `>= 1.51` (Components v2).
+- Frontend toolchain targets Node `>= 18` (Vite 5).
+
+## Publishing (GitHub / PyPI / Streamlit Cloud / gallery)
+
+Step-by-step instructions: [`PUBLISHING.md`](PUBLISHING.md).
+
+Order: push to GitHub → publish to PyPI → deploy `app.py` on Community Cloud →
+submit [`gallery/streamlit-drawable-konva.json`](gallery/streamlit-drawable-konva.json)
+as a PR to [streamlit/gallery](https://github.com/streamlit/gallery/tree/main/components/registry).
+
+## License
+
+MIT

streamlit_drawable_konva-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "streamlit-drawable-konva"
+version = "0.1.0"
+description = "Streamlit drawable canvas component using Konva.js (Components v2)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+  { name = "George Siogkas", email = "gsiogkas@cvrlab.com" },
+]
+dependencies = [
+  "streamlit>=1.51",
+  "numpy",
+  "pillow",
+]
+
+[project.urls]
+Homepage = "https://github.com/gsiogkas/streamlit-drawable-konva"
+Documentation = "https://github.com/gsiogkas/streamlit-drawable-konva#readme"
+Repository = "https://github.com/gsiogkas/streamlit-drawable-konva"
+Issues = "https://github.com/gsiogkas/streamlit-drawable-konva/issues"
+# Demo = "https://YOUR_APP_SLUG.streamlit.app"  # uncomment after Cloud deploy
+
+
+[project.optional-dependencies]
+demo = ["pandas"]
+devel = [
+  "wheel",
+  "pandas",
+]
+
+[dependency-groups]
+demo = ["pandas"]
+dev = ["pandas", "wheel"]
+
+[tool.setuptools.packages.find]
+include = ["streamlit_drawable_konva*"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+streamlit_drawable_konva = ["frontend/build/**/*", "pyproject.toml"]
+
+[tool.uv]
+default-groups = ["demo"]

streamlit_drawable_konva-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

streamlit_drawable_konva-0.1.0/streamlit_drawable_konva/__init__.py

@@ -0,0 +1,163 @@
+"""Streamlit Drawable Konva — Components v2 canvas with a compatible st_canvas API."""
+
+from __future__ import annotations
+
+import base64
+import io
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import numpy as np
+import streamlit as st
+from PIL import Image
+
+_COMPONENT = st.components.v2.component(
+    "streamlit-drawable-konva.st_canvas",
+    js="index.js",
+    html='<div class="react-root"></div>',
+)
+
+
+@dataclass
+class CanvasResult:
+    """Output of the drawable canvas component.
+
+    Attributes
+    ----------
+    image_data:
+        RGBA image as a NumPy array, or None before the first update.
+    json_data:
+        JSON scene dict (Konva-oriented objects), or None before the first update.
+    """
+
+    image_data: Optional[np.ndarray] = None
+    json_data: Optional[dict] = None
+
+
+def _data_url_to_image(data_url: str) -> Image.Image:
+    _, encoded = data_url.split(";base64,", 1)
+    return Image.open(io.BytesIO(base64.b64decode(encoded)))
+
+
+def _image_to_data_url(img: Image.Image) -> str:
+    buf = io.BytesIO()
+    img.convert("RGBA").save(buf, format="PNG")
+    b64 = base64.b64encode(buf.getvalue()).decode("ascii")
+    return f"data:image/png;base64,{b64}"
+
+
+def _resize_img(img: Image.Image, new_height: int, new_width: int) -> Image.Image:
+    return img.resize((new_width, new_height))
+
+
+def _noop() -> None:
+    """Required CCv2 on_change stub so default state keys are always present."""
+
+
+def st_canvas(
+    fill_color: str = "#eee",
+    stroke_width: int = 20,
+    stroke_color: str = "black",
+    background_color: str = "",
+    background_image: Optional[Image.Image] = None,
+    update_streamlit: bool = True,
+    height: int = 400,
+    width: int = 600,
+    drawing_mode: str = "freedraw",
+    initial_drawing: Optional[dict] = None,
+    display_toolbar: bool = True,
+    point_display_radius: int = 3,
+    key: Optional[str] = None,
+) -> CanvasResult:
+    """Create a Konva drawing canvas in a Streamlit app.
+
+    Compatible with the core API of ``streamlit-drawable-canvas`` /
+    ``streamlit-drawable-canvas-fix``, implemented on Streamlit Components v2.
+
+    Parameters
+    ----------
+    fill_color:
+        Fill color for shapes (CSS color). Defaults to ``"#eee"``.
+    stroke_width:
+        Stroke / brush width in pixels. Defaults to ``20``.
+    stroke_color:
+        Stroke color. Defaults to ``"black"``.
+    background_color:
+        Canvas background color. Empty string means transparent.
+        Overridden by ``background_image``. Changing this resets the drawing.
+    background_image:
+        Pillow image displayed behind drawings (resized to canvas size).
+        Not included in returned ``image_data``.
+    update_streamlit:
+        When True, send canvas data to Streamlit on mouse-up / object updates.
+    height:
+        Canvas height in pixels. Defaults to ``400``.
+    width:
+        Canvas width in pixels. Defaults to ``600``.
+    drawing_mode:
+        One of ``freedraw``, ``transform``, ``line``, ``rect``, ``circle``,
+        ``point``, ``polygon``. Defaults to ``freedraw``.
+    initial_drawing:
+        JSON scene to load (typically a previous ``json_data``).
+    display_toolbar:
+        Show undo / redo / clear toolbar.
+    point_display_radius:
+        Radius used when drawing points as circles.
+    key:
+        Optional Streamlit widget key.
+
+    Returns
+    -------
+    CanvasResult
+        ``image_data`` is an RGBA NumPy array; ``json_data`` is the scene dict.
+    """
+    background_image_url: Optional[str] = None
+    bg_color = background_color
+    if background_image is not None:
+        resized = _resize_img(background_image, height, width)
+        background_image_url = _image_to_data_url(resized)
+        bg_color = ""
+
+    scene: dict[str, Any] = (
+        {"version": "konva-1", "objects": []}
+        if initial_drawing is None
+        else dict(initial_drawing)
+    )
+    scene["background"] = bg_color
+
+    toolbar_h = 40 if display_toolbar else 0
+    component_height = height + toolbar_h + 8
+
+    raw = _COMPONENT(
+        key=key,
+        data={
+            "fillColor": fill_color,
+            "strokeWidth": stroke_width,
+            "strokeColor": stroke_color,
+            "backgroundColor": bg_color,
+            "backgroundImageURL": background_image_url,
+            "realtimeUpdateStreamlit": update_streamlit
+            and (drawing_mode != "polygon"),
+            "canvasHeight": height,
+            "canvasWidth": width,
+            "drawingMode": drawing_mode,
+            "initialDrawing": scene,
+            "displayToolbar": display_toolbar,
+            "displayRadius": point_display_radius,
+        },
+        default={"image_data_url": None, "json_data": None},
+        on_image_data_url_change=_noop,
+        on_json_data_change=_noop,
+        height=component_height,
+    )
+
+    image_data_url = getattr(raw, "image_data_url", None)
+    json_data = getattr(raw, "json_data", None)
+
+    if image_data_url is None:
+        return CanvasResult(image_data=None, json_data=json_data)
+
+    return CanvasResult(
+        image_data=np.asarray(_data_url_to_image(image_data_url)),
+        json_data=json_data,
+    )