A Python Framework for Interactive, SVG-Driven Web Infographics with Streamlit Integration
SIVO (SVG Interactive Vector Objects) is a Python framework that converts static SVG graphics into responsive, interactive web infographics using a Python-first workflow. It allows designers, analysts, and developers to attach behaviors—tooltips, drill-downs, navigation, and dynamic updates—to individual SVG paths without writing JavaScript.
The system bridges the gap between vector design tools and interactive web data visualization. A user provides an SVG file and maps SVG element IDs to Python-defined actions. SIVO processes the SVG into a canonicalized form, generates an interaction manifest, and exports a fully functional interactive web asset.
The primary deployment target is Python applications built with Streamlit, enabling live dashboards and operational interfaces. The system also supports static HTML export for standalone deployment.
- Convert static SVG diagrams into interactive web experiences.
- Enable Python developers to define interaction logic without writing JavaScript.
- Provide seamless integration with Streamlit applications.
- Ensure robustness against real-world SVG complexity.
- Produce responsive and mobile-friendly visual interfaces.
The first release will not attempt to:
- Replace full visualization libraries.
- Provide complex charting systems.
- Support animated SVG editing pipelines.
- Serve as a full design tool.
Instead, SIVO focuses strictly on interaction layers for existing SVG artwork.
A SIVO object represents a single identifiable SVG element that can respond to user interactions.
Examples:
| SVG Element | Possible Interaction |
|---|---|
<path id="room101"> |
Tooltip with room data |
<rect id="machineA"> |
Click to open status panel |
<g id="floor1"> |
Drill down to floor plan |
<path id="pipeline"> |
Color change when sensor updates |
Each SIVO object maps to a Python action definition.
Actions define behavior associated with SVG IDs.
| Action | Description |
|---|---|
| Tooltip | Display contextual information |
| URL | Navigate to external link |
| DrillDown | Load another SVG |
| Callback | Send event to Streamlit |
| Highlight | Change visual state |
SIVO is composed of five primary subsystems.
| Component | Role |
|---|---|
| SVG Normalizer | Parses and canonicalizes SVG files |
| Mapping Engine | Connects SVG IDs to Python actions |
| Bundle Generator | Creates interactive HTML packages |
| Frontend Runtime | Handles interactions in browser |
| Streamlit Bridge | Integrates SIVO with Streamlit apps |
Real-world SVG files contain nested transforms, symbol references, and inconsistent coordinate systems. SIVO solves this by canonicalizing the SVG before interaction logic is applied.
- Parse SVG structure
- Resolve
<use>references - Flatten nested
<g>transforms - Convert all paths into absolute coordinates
- Extract bounding boxes
- Generate metadata for hit detection
canonical_svg
metadata.json
Metadata example:
{
"objects": [
{
"id": "buildingA",
"bbox": [12.1, 45.6, 210.4, 160.2],
"type": "path"
}
]
}The normalizer will use:
- lxml
- BeautifulSoup
These provide reliable XML parsing and manipulation.
The mapping engine connects Python code to SVG elements.
Primary user-facing API, wrapping the internal Infographic logic to provide a seamless declarative interface.
from sivo import Sivo
sivo_app = Sivo.from_svg("campus.svg")
sivo_app.map(
"buildingA",
tooltip="<h3>Building A</h3>",
drill_to="buildingA.svg"
)
sivo_app.to_html("output.html")- Track mapped IDs
- Validate actions
- Generate interaction manifest
- Provide export functionality
All interactions are serialized into a manifest JSON file consumed by the browser runtime.
Example:
{
"objects": {
"buildingA": {
"tooltip": "<h3>Building A</h3>",
"drill_to": "buildingA.svg"
}
}
}This decouples Python logic from frontend execution.
The runtime handles all browser interactions.
Responsibilities:
- SVG rendering
- Hit detection
- Tooltip management
- Drill-down transitions
- Responsive scaling
Optional rendering layers may use:
- Apache ECharts for map-style rendering if needed.
However, SIVO primarily relies on native SVG interaction.
SVG elements must scale correctly inside flexible layouts.
SIVO implements:
The runtime monitors container dimensions and rescales the SVG accordingly.
Key behaviors:
- Maintain aspect ratio from
viewBox - Correct hit detection after scaling
- Maintain pointer accuracy
Small paths can become difficult to click.
SIVO implements two mechanisms:
Adds invisible expanded shapes behind small paths.
For large SVGs (>500 paths), SIVO creates a client-side spatial index to speed up hit detection.
SIVO tooltips use Shadow DOM encapsulation.
Benefits:
- Prevent CSS conflicts
- Support complex HTML
- Allow embedded media
Capabilities:
| Feature | Supported |
|---|---|
| HTML content | Yes |
| Embedded dashboards | Yes |
| iframes | Yes (sandboxed) |
| dynamic updates | Yes |
User-provided HTML can create security risks.
SIVO implements:
HTML content is sanitized before export.
Embedded iframes include strict sandbox rules.
Example CSP provided for deployment.
Hierarchical navigation enables complex visual storytelling.
Example:
Campus Map
└ Building A
└ Floor 1
- User clicks SVG object
- Runtime loads secondary SVG
- Transition animation plays
- Breadcrumb navigation updates
- Crossfade (default)
- Scale transition
- Optional morphing
Themes control visual styles across interactions.
Example:
Theme(
hover_color="#ff6600",
border_width=2,
glow=True
)Theme controls:
- hover colors
- outline thickness
- highlight styles
- animation duration
SIVO provides first-class integration with:
Streamlit
A custom component renders the SIVO bundle inside a Streamlit app. Note: Any Streamlit component MUST be a V2 component (st.components.v2.component). See V2 Components Documentation and V2 Components with file-backed assets for more information.
Capabilities:
| Feature | Supported |
|---|---|
| Live tooltip updates | Yes |
| Click callbacks | Yes |
| Dynamic coloring | Yes |
| Drill-down navigation | Yes |
import streamlit as st
from sivo import Sivo
from sivo.streamlit.component import sivo_component
sivo_app = Sivo.from_svg("factory.svg")
sivo_app.map("machineA", tooltip="Machine A")
result = sivo_component(sivo_app.infographic, key="sivo_example")The CLI assists users in preparing SVG projects.
Initialize project
sivo init diagram.svg
Export bundle
sivo export project.yml
Validate SVG
sivo validate diagram.svg
sivo/
__init__.py
core/
sivo.py
infographic.py
actions.py
config.py
svg/
normalizer.py
parser.py
transforms.py
runtime/
bundle_generator.py
templates/
frontend/
sivo_runtime.js
tooltip.js
drilldown.js
streamlit/
component.py
cli/
commands.py
tests/
examples/
docs/
Deliverables:
- SVG parser
- canonicalizer (Robust
<use>reference resolution, proper wrapping, and cycle detection completed) - metadata extraction
- bounding box calculation (Robust parser implemented for SVG paths handling relative/absolute commands and exponential notation)
Deliverables:
- Action classes
- manifest generator
- tooltip system (Shadow DOM encapsulated)
- hit detection
Deliverables:
- JS runtime
- resize handling
- drill-down transitions (SVG loading & chart rebuilding fixed)
- event system (Full Streamlit callback sync)
Deliverables:
- Streamlit component (V2 API)
- example apps
- dynamic updates
Deliverables:
- Configuration Engine (JSON/dict parsing)
- CLI tool
- Sivo Declarative Orchestrator
- pip packaging
- documentation
- example gallery
- SVG parsing
- transform flattening
- metadata generation
- runtime interaction
- tooltip rendering
- drill-down navigation
- HTML sanitization
- iframe sandboxing
Goal:
- <50ms interaction latency
- 200+ paths without slowdown
Documentation will include:
- Quickstart guide
- API reference
- SVG preparation guidelines
- Streamlit examples
- troubleshooting guide
The project will be distributed via:
pip install sivo
Assets include:
- Python package
- JS runtime bundle
- CLI tool
- example datasets
Interactive building diagrams showing occupancy and sensor data.
Machines displayed as SVG elements updating status in real time.
Power grids, pipelines, and network systems.
Biology, anatomy, engineering schematics.
Version 1 of SIVO is considered successful when:
- Developers can convert an SVG to an interactive asset in under 10 minutes.
- Streamlit dashboards can embed SIVO graphics easily.
- The system handles real-world SVG complexity.
- Interactions remain responsive with hundreds of paths.
Future versions may include:
- Interactive SVG editor
- visual mapping GUI
- real-time websocket updates
- automatic path labeling
- path morph animations
SIVO (SVG Interactive Vector Objects) provides a robust framework for transforming static SVG designs into interactive data-driven interfaces using Python. By combining SVG normalization, Python-defined interaction logic, and Streamlit integration, SIVO enables developers to build powerful visual interfaces without complex frontend engineering.
The system prioritizes reliability, accessibility, and simplicity while remaining extensible for advanced visualization needs.
1. Critical Vulnerability: XML External Entity (XXE) Injection (Completed)
- Location:
src/sivo/svg/parser.py, Lines 9-14 - Assessment: The application parses SVG (XML) files using
lxml.etree.parse()without disabling network access or entity resolution. This exposes the application to XXE injection vulnerabilities, potentially allowing attackers to read local files, conduct Server-Side Request Forgery (SSRF) attacks, or cause Denial of Service (DoS) if malicious or untrusted SVGs are uploaded and processed. - Proposed Solution:
def __init__(self, filepath_or_string: str, is_file: bool = True): # Explicitly secure the parser against XXE parser = etree.XMLParser(resolve_entities=False, no_network=True) if is_file: with open(filepath_or_string, 'rb') as f: self.tree = etree.parse(f, parser=parser) self.root = self.tree.getroot() else: self.root = etree.fromstring(filepath_or_string.encode('utf-8'), parser=parser) self.tree = etree.ElementTree(self.root)
- Trade-off: Disabling external entities improves security immensely but may break unusual legacy SVG files that legitimately rely on external entities. This does not change the API contract.
2. Security Risk: Cross-Site Scripting (XSS) via DOM Injection (Completed)
- Location:
src/sivo/runtime/templates/echarts.html, Lines 117-124 - Assessment: The JS runtime injects user-defined HTML content (
action.content) into the DOM viainfoContent.innerHTML = htmlContent;. Even though it is encapsulated in a Shadow DOM, this is still vulnerable to XSS if the HTML configuration originates from untrusted sources (e.g.,<img src="x" onerror="alert(1)">). - Proposed Solution:
// Introduce a lightweight client-side sanitizer function sanitizeHTML(str) { var temp = document.createElement('div'); temp.innerHTML = str; var scripts = temp.getElementsByTagName('script'); for (var i = scripts.length - 1; i >= 0; i--) { scripts[i].parentNode.removeChild(scripts[i]); } // Iterate and remove inline event handlers (on*) var allElements = temp.getElementsByTagName("*"); for (var i = 0, len = allElements.length; i < len; i++) { var el = allElements[i]; for (var j = el.attributes.length - 1; j >= 0; j--) { if (el.attributes[j].name.toLowerCase().startsWith('on')) { el.removeAttribute(el.attributes[j].name); } } } return temp.innerHTML; } if (hasInteraction && htmlContent) { infoContent.innerHTML = sanitizeHTML(htmlContent); infoPanel.classList.add('active'); }
- Trade-off: Adds minor processing overhead on the frontend and strips out legitimately intended scripts, slightly reducing functionality if developers wanted executable code inside tooltips.
3. Logical Error: Misaligned Coordinate Parsing (Completed)
- Location:
src/sivo/svg/metadata.py, Lines 62-63 - Assessment: When calculating the bounding box for
polygonorpolyline, the code assumes thepointsarray will always contain an even number of coordinates after regex parsing. If an SVG contains a malformed points string (e.g., an odd number of numbers),xsandyswill misalign, leading to mathematically skewed bounding box calculations. - Proposed Solution:
elif tag_name in ['polygon', 'polyline']: points_str = elem.get('points', '') coords = [float(p) for p in re.findall(r'[-+]?(?:\d*\.\d+|\d+)', points_str)] if len(coords) < 2: return None # Ensure an even number of coordinates to prevent misalignment if len(coords) % 2 != 0: coords = coords[:-1] xs = coords[0::2] ys = coords[1::2] return [min(xs), min(ys), max(xs), max(ys)]
- Trade-off: Dropping a trailing orphaned coordinate changes strict parsing behavior in favor of fault tolerance. It ensures the application won't crash or generate corrupted spatial metadata.
1. Performance: O(n) Mapping Bottleneck (Completed)
- Location:
src/sivo/core/infographic.py, Lines 77-83 (mapmethod) - Assessment: The
mapmethod performs a linear searchO(n)overself.elementsevery time an element is mapped. When loading from a JSON configuration containingmmappings, this results inO(n * m)complexity, severely bottlenecking performance for complex SVGs with thousands of elements. - Proposed Solution:
# Inside __init__, build an O(1) lookup map def __init__(self, parser: SVGParser): self.parser = parser self.elements = self.parser.process_elements() self.mappings: Dict[str, InteractionMapping] = {} self._element_lookup: Dict[str, dict] = {} for elem in self.elements: self.mappings[elem['name']] = InteractionMapping(id=elem['id']) self._element_lookup[elem['id']] = elem self._element_lookup[elem['name']] = elem # Inside the map method, replace the loop: def map(self, element_id: str, ...): target_elem = self._element_lookup.get(element_id) if not target_elem: raise ValueError(f"Element with id/name '{element_id}' not found in SVG.") elem_name = target_elem['name'] mapping = self.mappings[elem_name] # ... logic continues
- Trade-off: Slightly increases memory usage due to the
_element_lookupdictionary, but vastly improves computational speed fromO(n)toO(1)per mapped element.
2. Readability & Maintenance: Monolithic Logic (Completed)
- Location:
src/sivo/svg/metadata.py, Lines 68-185 (calculate_path_bboxmethod) - Assessment:
calculate_path_bboxis a massive, deeply nested function handling multiple SVG path commands within a single monolithicwhileloop. This violates the Single Responsibility Principle, making it difficult to maintain, read, or write targeted unit tests for specific SVG commands. - Proposed Solution:
class PathBBoxCalculator: def __init__(self): self.min_x = self.min_y = float('inf') self.max_x = self.max_y = float('-inf') self.curr_x = self.curr_y = 0.0 def update_bounds(self, *coords): for i in range(0, len(coords), 2): x, y = coords[i], coords[i+1] self.min_x, self.max_x = min(self.min_x, x), max(self.max_x, x) self.min_y, self.max_y = min(self.min_y, y), max(self.max_y, y) def handle_M(self, x, y, is_relative): if is_relative: x += self.curr_x y += self.curr_y self.curr_x, self.curr_y = x, y self.update_bounds(x, y) # ... other handlers (handle_L, handle_C, etc.) ... def calculate_path_bbox(d_str: str) -> Optional[List[float]]: # Tokenize and pass to PathBBoxCalculator instance pass
- Trade-off: Refactoring to a class or a dispatcher model introduces slight function call overhead, but drastically improves readability, maintainability, and testing isolation.
3. Optimization: Arbitrary Cycle Prevention (Completed)
- Location:
src/sivo/svg/normalizer.py, Lines 69-79 (resolve_use_tagsmethod) - Assessment: The cycle detection logic for SVG
<use>references relies on an arbitrary depth counter (depth > 20). This heuristic approach wastes CPU cycles on deep, legitimately nested trees while failing to explicitly catch true circular dependencies in an optimized manner. - Proposed Solution:
# Pass a specific visited_ids set alongside the queue items initial_uses = [(u, set()) for u in self.root.xpath('.//svg:use', namespaces=self.namespaces)] queue = collections.deque(initial_uses) while queue: use_elem, visited = queue.popleft() # ... fetch href ... ref_id = href[1:] if ref_id in visited: parent.remove(use_elem) # Cycle detected continue new_visited = visited.copy() new_visited.add(ref_id) # ... clone logic ... for new_use in new_uses: queue.append((new_use, new_visited))
- Trade-off: Memory overhead increases marginally because each queue item maintains its own set of visited IDs. However, it provides guaranteed mathematical loop prevention.
1. Programmatic Zoom & Pan API (Completed - Center Extraction via Python Metadata)
- Utility: Currently, the ECharts implementation allows manual user panning (
roam: true). Exposing an API method (e.g.,sivo_app.zoom_to("element_id")) that calculates the target's metadatabboxand triggers ECharts'dispatchActionto automatically focus and center on a specific SVG region would be highly valuable for guided storytelling or presentation flows.
2. Bi-directional Streamlit State Synchronization (Completed - Dynamic Colors & Hover Callbacks)
- Utility: SIVO can send click callbacks to Streamlit via the V2 component, but it currently lacks a way for Streamlit to update the SVG state without initiating a full backend re-render. Implementing a JS frontend listener that accepts state mutations from Streamlit (e.g., changing colors dynamically based on live data feeds) would make the infographics truly reactive and real-time.
3. HTML/DOM Overlay Positioning System / Asset Injection (Completed - Absolute Positioning over SVG via BBox)
- Utility: Allow developers to define custom HTML overlays (like React-style tooltips or floating charts) that are absolutely positioned over specific SVG coordinates, derived from the Python bounding box metadata. This enables rich annotations and complex UI components that live outside the strict ECharts
<canvas>bounds, significantly enhancing the visual capabilities of the framework.
4. Multi-View Standalone HTML Generation (Completed)
- Utility: Upgraded the
drill_toarchitecture via a newSivoProjectwrapper to allow developers to package multiple SVG views into a single, offline HTML file. Clicking elements mapped withdrill_to="view_id"instantly transitions the ECharts canvas and overlay logic entirely on the client side without needing Streamlit or separate.svgnetwork fetches.