gd-sofa-utils 0.0.1__tar.gz

gd_sofa_utils-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__
+.venv
+out
+*.egg-info
+dist
+.pytest_cache
+.coverage
+site
+public
+output
+*.ini
+*.view
+

gd_sofa_utils-0.0.1/.gitlab-ci.yml

@@ -0,0 +1,118 @@
+stages:
+  - test
+  - build
+  - publish
+  - deploy_doc
+
+image: python:3.12
+
+variables:
+  GIT_DEPTH: "0"                      # setuptools-scm needs full history/tags
+  GIT_FETCH_EXTRA_FLAGS: "--tags"     # make sure tags are fetched
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+  PYTHONDONTWRITEBYTECODE: "1"
+  PYTHONUNBUFFERED: "1"
+  UV_CACHE_DIR: "$CI_PROJECT_DIR/.uv-cache"
+
+cache:
+  key: "${CI_PROJECT_NAME}"
+  paths:
+    - .venv/
+    - .uv-cache/
+
+before_script:
+  - python -m pip install -U pip
+  - python -m pip install -U uv
+
+test:
+  stage: test
+  tags:
+    - ci.inria.fr
+    - small
+  script:
+    - uv sync --frozen --group dev
+    - uv run pytest
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/'
+    - when: never
+
+build:
+  stage: build
+  tags:
+    - ci.inria.fr
+    - small
+  needs: ["test"]
+  script:
+    - uv sync --frozen --group dev
+    - uv run python -m build
+    - |
+      python - <<'PY'
+      import os, re, glob, subprocess, sys
+      tag = os.environ.get("CI_COMMIT_TAG", "")
+
+      m = re.fullmatch(r"v(\d+\.\d+\.\d+)", tag)
+      if not m:
+        raise SystemExit(f"Invalid tag format: {tag!r} (expected vX.Y.Z)")
+      tag_ver = m.group(1)
+
+      wheels = glob.glob("dist/*.whl")
+      if not wheels:
+        raise SystemExit("No wheel found in dist/")
+      wheel = wheels[0]
+
+      subprocess.check_call([sys.executable, "-m", "pip", "install", "--no-deps", "--force-reinstall", wheel])
+      import importlib.metadata as md
+      ver = md.version("gd-sofa-utils")
+      if ver != tag_ver:
+        raise SystemExit(f"Version mismatch: wheel={ver!r} tag={tag_ver!r}")
+      print(f"OK: wheel version {ver} matches tag {tag}")
+      PY
+  artifacts:
+    when: always
+    expire_in: 7 days
+    paths:
+      - dist/
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/'
+    - when: never
+
+publish_pypi:
+  stage: publish
+  tags:
+    - ci.inria.fr
+    - small
+  needs: ["build"]
+  script:
+    - uv sync --frozen --group dev
+    - |
+      python - <<'PY'
+      import os
+      if not os.environ.get("PYPI_API_TOKEN"):
+        raise SystemExit("Missing PYPI_API_TOKEN CI variable.")
+      PY
+    - export TWINE_USERNAME="__token__"
+    - export TWINE_PASSWORD="$PYPI_API_TOKEN"
+    - |
+      if [ -n "$PYPI_REPOSITORY_URL" ]; then
+        uv run twine upload --repository-url "$PYPI_REPOSITORY_URL" dist/*
+      else
+        uv run twine upload dist/*
+      fi
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/'
+    - when: never
+
+pages:
+  stage: deploy_doc
+  tags:
+    - ci.inria.fr
+    - small
+  rules:
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+  script:
+    - uv sync --frozen --extra docs
+    - uv run mkdocs build --strict --site-dir public
+  artifacts:
+    paths:
+      - public
+

gd_sofa_utils-0.0.1/LICENSE

@@ -0,0 +1,16 @@
+The GNU General Public License (GPL)
+
+Copyright (c) 2026, Gaëtan Desrues, Inria, France
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

gd_sofa_utils-0.0.1/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: gd-sofa-utils
+Version: 0.0.1
+Requires-Python: ==3.12.*
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gd-py-utils
+Requires-Dist: randomname
+Requires-Dist: colour
+Requires-Dist: param
+Requires-Dist: treelib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-mermaid2-plugin; extra == "docs"
+Requires-Dist: mkdocs-snippets; extra == "docs"
+Requires-Dist: mkdocs-exclude; extra == "docs"
+Requires-Dist: mkdocstrings-python; extra == "docs"
+Dynamic: license-file
+
+# gdsofa
+
+**gdsofa** is a lightweight Python library for building and running [SOFA](https://www.sofa-framework.org/) (Simulation Open Framework Architecture) scenes programmatically. It provides a scene graph API (nodes, components, parameters, controllers) and a runner for headless or GUI simulations.
+
+[**Docs**]()
+
+## Installation
+
+```bash
+pip install gd-sofa-utils
+```

gd_sofa_utils-0.0.1/README.md

@@ -0,0 +1,11 @@
+# gdsofa
+
+**gdsofa** is a lightweight Python library for building and running [SOFA](https://www.sofa-framework.org/) (Simulation Open Framework Architecture) scenes programmatically. It provides a scene graph API (nodes, components, parameters, controllers) and a runner for headless or GUI simulations.
+
+[**Docs**]()
+
+## Installation
+
+```bash
+pip install gd-sofa-utils
+```

gd_sofa_utils-0.0.1/docs/api.md

@@ -0,0 +1,37 @@
+# API Reference
+
+## Package
+
+::: gdsofa
+
+## Scene and runner
+
+::: gdsofa.sofawrap
+
+## Parameters
+
+::: gdsofa.sofa_parameters
+
+## SOFA loader
+
+::: gdsofa.load_SOFA
+
+## Controllers
+
+::: gdsofa.controller
+
+## Core (nodes, components, links)
+
+::: gdsofa.core
+
+## Utilities
+
+::: gdsofa.utils
+
+## SOFA component wrappers
+
+::: gdsofa.comps.base_component
+
+## Visual flags
+
+::: gdsofa.visual

gd_sofa_utils-0.0.1/docs/extra.css

@@ -0,0 +1,3 @@
+.md-main__inner {
+  padding-bottom: 3rem;
+}

gd_sofa_utils-0.0.1/docs/guide.md

@@ -0,0 +1,123 @@
+# User guide
+
+## Requirements
+
+gdsofa requires a SOFA build. Set the **`SOFA_ROOT`** environment variable to your SOFA build directory (the path that contains `lib/python3/site-packages` or `lib/python/site-packages`). The library uses it to extend `sys.path` and load SOFA’s Python bindings.
+
+```bash
+export SOFA_ROOT=/path/to/sofa/build
+```
+
+If `SOFA_ROOT` is missing, `load_SOFA()` and `RunSofa` will raise an error.
+
+gdsofa also depends on [gdutils](https://gdutils-a2ef81.gitlabpages.inria.fr/) for JSON I/O, timing, and iterable helpers (see [Utilities](#utilities)).
+
+## Scene graph
+
+The scene is a tree of **nodes**. Each node can have child nodes and **components** (SOFA objects).
+
+### Root and nodes
+
+- **`RootNode(**kw)`** — Creates the root node of the scene and adds a default visual manager loop. Use this as the top-level node.
+- **`Node(name, parent=None, gravity=None, **kwargs)`** — Creates a child node. You typically create children with **`parent.add_child(name, **kwargs)`**.
+- Add components to a node with **`node + component`** (e.g. `root + DefaultAnimationLoop()`).
+
+Example:
+
+```python
+import gdsofa as gs
+
+root = gs.RootNode()
+root + gs.DefaultAnimationLoop()
+
+# Add a child node and components
+child = root.add_child("my_node")
+child + gs.MechanicalObject()
+# ... more components
+```
+
+### Core types
+
+- **Components** — Use the classes from `gdsofa.comps` (e.g. `DefaultAnimationLoop`, `MechanicalObject`, `EulerImplicitSolver`, `MeshVTKLoader`, `Gravity`). They are added to nodes with `+`.
+- **Links** — Use `Link` and `MultiLink` from `gdsofa.core` to reference other components (e.g. for mappings or loaders).
+- **Objects** — For custom SOFA types, use `Object(class_name, **kwargs)` from `gdsofa.core`.
+
+## Parameters
+
+**`BaseSOFAParams`** holds simulation and I/O settings. Main attributes:
+
+- **`out_dir`** — Output directory (created if missing).
+- **`n`** — Number of iterations (default 100).
+- **`dt`** — Time step (default 1; often overridden, e.g. 0.005).
+- **`scale`** — Scaling for SOFA loaders.
+- **`data_path`** — Optional data input directory.
+
+You can load/save parameters as JSON:
+
+- **`params.dump_json(fname)`** / **`params.save()`** — Write current parameters (e.g. to `out_dir/params.json`).
+- **`BaseSOFAParams.from_json(fname)`** / **`BaseSOFAParams.from_dir(dname)`** — Load from file or from a directory containing `params.json`.
+
+Example:
+
+```python
+params = gs.BaseSOFAParams(out_dir="/path/to/out", n=200, dt=0.005)
+params.save()
+# later:
+params = gs.BaseSOFAParams.from_dir("/path/to/out")
+```
+
+## Controllers
+
+Custom logic per time step is done with **controllers**. Subclass **`BaseSOFAController`** and override:
+
+- **`before_animate(ctx)`** — Called before each simulation step.
+- **`after_animate(ctx)`** — Called after each step.
+
+The controller receives `root` (the gdsofa root node) and `params` (the `BaseSOFAParams` instance). Use `self.get_node(name)` and `self.root.find(...)` to reach nodes and components.
+
+Pass controller **classes** (not instances) to **`RunSofa`**:
+
+```python
+class MyController(gs.BaseSOFAController):
+    def after_animate(self, ctx):
+        # e.g. log or export data
+        pass
+
+sofa = gs.RunSofa(root, params, MyController)
+sofa.run(gui=False)
+```
+
+## Running
+
+**`RunSofa(root, params=None, *controllers)`** builds the SOFA scene from the gdsofa graph and optionally attaches controllers.
+
+- **`params`** — Optional. If omitted, a default `BaseSOFAParams()` is used (you should set at least `out_dir` for file output).
+- **`*controllers`** — Optional controller classes.
+
+Methods:
+
+- **`run(gui=False, std_to_file=False, viewer="qglviewer", title="MyProject")`** — Runs the simulation.
+  - **`gui=True`** — Opens the SOFA GUI (requires Qt and SOFA GUI plugins).
+  - **`gui=False`** — Headless: runs `n` steps (from `params`).
+  - **`std_to_file=True`** — Redirects stdout/stderr to files under `params.out_dir` (requires `out_dir` set).
+- **`to_file(fname=None, clean_paths=False, doc=None)`** — Exports the scene as a Python script. Default path is `params.out_dir/sofa_scene.py` if `out_dir` is set.
+- **`import_plugins()`** — Called during `__init__`; imports SOFA plugins required by the scene graph.
+
+Example (headless with output directory):
+
+```python
+params = gs.BaseSOFAParams(out_dir="/path/to/out", n=100, dt=0.005)
+sofa = gs.RunSofa(root, params)
+result = sofa.run(gui=False, std_to_file=True)
+result.save()  # writes run_stats.json under out_dir
+sofa.to_file() # writes sofa_scene.py under out_dir
+```
+
+## Utilities
+
+**`gdsofa.utils`** provides helpers used internally and available for your scripts:
+
+- **From [gdutils](https://gdutils-a2ef81.gitlabpages.inria.fr/)**: `load_json`, `dump_json`, `Timer`, and `as_iterable` (alias of gdutils’ `get_iterable`). gdsofa re-exports these to avoid redundancy; see the gdutils docs for full details.
+- **gdsofa-specific**: `dump_path` (create directory and return path), `Munch` / `munchify` (dict with attribute access), `JsonEncoder` (Path and numpy in JSON), `StdRedirect`, and helpers such as `ensure_ext`, `path_insert_before`, `random_name`, `unique_id`.
+
+For path management relative to your script (e.g. output directories), you can use **`gd.fPath(__file__, "out", mkdir=True)`** from gdutils directly.

gd_sofa_utils-0.0.1/docs/index.md

@@ -0,0 +1,34 @@
+# gdsofa
+
+**gdsofa** is a lightweight Python library for building and running [SOFA](https://www.sofa-framework.org/) (Simulation Open Framework Architecture) scenes programmatically. It provides a scene graph API (nodes, components, parameters, controllers) and a runner for headless or GUI simulations.
+
+## Requirements
+
+- Python 3.12 (same as SOFAPython3 version)
+- A SOFA build: set the **`SOFA_ROOT`** environment variable to your SOFA build directory.
+
+## Installation
+
+```bash
+pip install gd-sofa-utils
+```
+
+## Quick start
+
+Build a minimal scene, attach parameters, and run it (GUI or headless):
+
+```python
+import gdsofa as gs
+
+root = gs.RootNode()
+root + gs.DefaultAnimationLoop()
+
+params = gs.BaseSOFAParams(out_dir="/path/to/out")
+sofa = gs.RunSofa(root, params)
+sofa.run(gui=True)
+```
+
+Next steps:
+
+- [User guide](guide.md) — requirements, scene graph, parameters, controllers, running.
+- [API Reference](api.md) — full API documentation.

gd_sofa_utils-0.0.1/docs/setup.js

@@ -0,0 +1,214 @@
+(function () {
+  "use strict";
+
+  // ---- Utils ---------------------------------------------------------------
+
+  const onReady = (cb) => {
+    if (typeof document$ !== "undefined" && document$?.subscribe) {
+      document$.subscribe(({ body }) => cb(body));
+    } else {
+      document.addEventListener("DOMContentLoaded", () => cb(document));
+    }
+  };
+
+  // ---- KaTeX auto-render ---------------------------------------------------
+
+  const renderMath = (root) => {
+    if (!window.renderMathInElement) return;
+
+    renderMathInElement(root, {
+      delimiters: [
+        { left: "$$", right: "$$", display: true },
+        { left: "$", right: "$", display: false },
+        { left: "\\(", right: "\\)", display: false },
+        { left: "\\[", right: "\\]", display: true },
+      ],
+      throwOnError: false,
+    });
+  };
+
+  // ---- Mermaid init (once) -------------------------------------------------
+
+  let mermaidInited = false;
+  const initMermaidOnce = () => {
+    if (mermaidInited) return;
+    if (!window.mermaid?.initialize) return;
+
+    // mkdocs-mermaid2-plugin usually drives rendering;
+    // we only ensure mermaid is configured.
+    mermaid.initialize({ startOnLoad: true });
+    mermaidInited = true;
+  };
+
+  // ---- Mermaid popup modal + pan/zoom --------------------------------------
+
+  let panZoom = null;
+
+  const destroyPanZoom = () => {
+    if (!panZoom) return;
+    try {
+      panZoom.destroy();
+    } catch {
+      // ignore
+    }
+    panZoom = null;
+  };
+
+  const ensureMermaidModal = () => {
+    let modal = document.getElementById("mermaid-modal");
+    if (modal) return modal;
+
+    modal = document.createElement("div");
+    modal.id = "mermaid-modal";
+    modal.style.cssText = `
+      position: fixed; inset: 0; z-index: 9999;
+      display: none; align-items: center; justify-content: center;
+      background: rgba(0,0,0,.55);
+      padding: 24px;
+    `;
+
+    const panel = document.createElement("div");
+    panel.id = "mermaid-modal-panel";
+    panel.style.cssText = `
+      position: relative;
+      width: min(1200px, 96vw);
+      height: min(800px, 92vh);
+      background: var(--md-default-bg-color, #fff);
+      border-radius: 12px;
+      box-shadow: 0 10px 30px rgba(0,0,0,.35);
+      overflow: hidden;
+    `;
+
+    const close = document.createElement("button");
+    close.type = "button";
+    close.textContent = "✕";
+    close.setAttribute("aria-label", "Close");
+    close.style.cssText = `
+      position: absolute; top: 10px; right: 10px; z-index: 3;
+      border: 0; border-radius: 10px;
+      padding: 6px 10px; cursor: pointer;
+      background: rgba(0,0,0,.08);
+    `;
+
+    const content = document.createElement("div");
+    content.id = "mermaid-modal-content";
+    content.style.cssText = `
+      width: 100%; height: 100%;
+      overflow: hidden;
+      padding: 0;
+    `;
+
+    const hide = () => {
+      destroyPanZoom();
+      modal.style.display = "none";
+      // Clean content to release references
+      content.replaceChildren();
+    };
+
+    close.addEventListener("click", hide);
+    modal.addEventListener("click", (e) => {
+      if (e.target === modal) hide();
+    });
+    document.addEventListener("keydown", (e) => {
+      if (e.key === "Escape" && modal.style.display !== "none") hide();
+    });
+
+    panel.appendChild(close);
+    panel.appendChild(content);
+    modal.appendChild(panel);
+    document.body.appendChild(modal);
+    return modal;
+  };
+
+  const openMermaidInModal = (svg) => {
+    const modal = ensureMermaidModal();
+    const content = document.getElementById("mermaid-modal-content");
+
+    destroyPanZoom();
+
+    // Wrap to allow svg-pan-zoom to size properly
+    const wrap = document.createElement("div");
+    wrap.style.cssText = `
+      width: 100%;
+      height: 100%;
+      overflow: hidden;
+      touch-action: none;
+      background: var(--md-default-bg-color, #fff);
+    `;
+
+    const clone = svg.cloneNode(true);
+
+    // Responsive sizing; pan/zoom handles viewBox transforms
+    clone.removeAttribute("width");
+    clone.removeAttribute("height");
+    clone.style.width = "100%";
+    clone.style.height = "100%";
+    clone.style.display = "block";
+
+    wrap.appendChild(clone);
+    content.replaceChildren(wrap);
+
+    modal.style.display = "flex";
+
+    if (window.svgPanZoom) {
+      // Needs to be in DOM + visible
+      requestAnimationFrame(() => {
+        panZoom = svgPanZoom(clone, {
+          zoomEnabled: true,
+          panEnabled: true,
+          controlIconsEnabled: true,
+          fit: true,
+          center: true,
+          minZoom: 0.1,
+          maxZoom: 50,
+          dblClickZoomEnabled: true,
+          mouseWheelZoomEnabled: true,
+          preventMouseEventsDefault: true,
+        });
+      });
+    }
+  };
+
+  const attachMermaidPopupButtons = (root) => {
+    const blocks = root.querySelectorAll(".mermaid");
+    for (const block of blocks) {
+      const svg = block.querySelector("svg");
+      if (!svg) continue;
+
+      if (block.dataset.popupAttached === "1") continue;
+      block.dataset.popupAttached = "1";
+
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.textContent = "Open";
+      btn.style.cssText = `
+        margin: 6px 0 10px 0;
+        padding: 4px 10px;
+        border-radius: 10px;
+        border: 1px solid rgba(0,0,0,.15);
+        background: transparent;
+        cursor: pointer;
+        font: inherit;
+      `;
+
+      btn.addEventListener("click", () => openMermaidInModal(svg));
+
+      block.parentElement?.insertBefore(btn, block);
+    }
+  };
+
+  // ---- Main hook -----------------------------------------------------------
+
+  onReady((body) => {
+    initMermaidOnce();
+    renderMath(body);
+
+    // Mermaid rendering can be async; retry briefly to catch SVG insertion
+    let tries = 0;
+    const tick = () => {
+      attachMermaidPopupButtons(body);
+      if (++tries < 12) setTimeout(tick, 150);
+    };
+    tick();
+  });
+})();

gd_sofa_utils-0.0.1/examples/general_example.py

@@ -0,0 +1,25 @@
+import logging
+
+import gdutils as gd
+import gdsofa as gs
+
+
+def main():
+    out = gd.fPath(__file__, "out")
+
+    root = gs.RootNode()
+    root + gs.DefaultAnimationLoop()
+    
+    params = gs.BaseSOFAParams(out_dir=out)
+    
+    sofa = gs.RunSofa(root, params)
+    sofa.run(gui=True)
+
+
+log = logging.getLogger(__name__)
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    log = gd.get_logger()
+
+    main()

gd_sofa_utils-0.0.1/gd_sofa_utils.egg-info/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: gd-sofa-utils
+Version: 0.0.1
+Requires-Python: ==3.12.*
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gd-py-utils
+Requires-Dist: randomname
+Requires-Dist: colour
+Requires-Dist: param
+Requires-Dist: treelib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-mermaid2-plugin; extra == "docs"
+Requires-Dist: mkdocs-snippets; extra == "docs"
+Requires-Dist: mkdocs-exclude; extra == "docs"
+Requires-Dist: mkdocstrings-python; extra == "docs"
+Dynamic: license-file
+
+# gdsofa
+
+**gdsofa** is a lightweight Python library for building and running [SOFA](https://www.sofa-framework.org/) (Simulation Open Framework Architecture) scenes programmatically. It provides a scene graph API (nodes, components, parameters, controllers) and a runner for headless or GUI simulations.
+
+[**Docs**]()
+
+## Installation
+
+```bash
+pip install gd-sofa-utils
+```