monomech 0.1.0__tar.gz

monomech-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

monomech-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md LICENSE mkdocs.yml
+recursive-include docs *.md
+recursive-include src/monomech/assets *.yml
+recursive-include examples *.ipynb *.py *.md *.fbx *.osim

monomech-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: monomech
+Version: 0.1.0
+Summary: MonoMech: single-camera biomechanics from video to kinematics and kinetics
+Author: OpenAI for user
+License: MIT
+Keywords: biomechanics,mediapipe,opensim,pose estimation,single camera,kinematics,kinetics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: opencv-python>=4.8
+Requires-Dist: plotly>=5.20
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tqdm>=4.66
+Requires-Dist: typing-extensions>=4.9
+Provides-Extra: pose
+Requires-Dist: mediapipe>=0.10.33; extra == "pose"
+Provides-Extra: viz
+Requires-Dist: ipython>=8.0; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: nbformat>=5.10; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# MonoMech
+
+**MonoMech** is a single-camera-to-biomechanics Python library for turning one video path or a list of video paths into inspectable kinematics and kinetics.
+
+It is designed to be:
+
+- **modular**: each stage is callable on its own
+- **notebook friendly**: every stage returns a dataframe-centric result object and optional HTML visualization
+- **OpenSim aware**: exports `TRC`, `MOT`, `STO`, `CSV`, and builds inverse-kinematics / inverse-dynamics workflows
+- **publishable**: ships with `pyproject.toml`, docs, tests, conda recipe, and example notebooks
+
+## Main ideas
+
+```python
+from monomech import MonoMechPipeline, PipelineConfig, dumbbell_force
+
+pipeline = MonoMechPipeline(
+    PipelineConfig(output_root="outputs")
+)
+
+trial = pipeline.run(
+    "subject01_squat.mp4",
+    model_path="examples/assets/Mediapipe_Model.osim",
+    fbx_path="examples/assets/MovisionModel.fbx",
+    external_forces=[
+        dumbbell_force(side="right", mass_kg=12.5, point_in_body=(0.0, -0.02, 0.0))
+    ],
+)
+
+trial.pose2d.inspect().head()
+trial.poseworld.inspect().head()
+trial.inverse_kinematics.inspect().head()
+trial.inverse_dynamics.inspect().head()
+trial.visualizations["pose_analysis"]
+trial.visualizations["rig_viewer"]
+```
+
+## Stage-by-stage API
+
+Each stage can also run on its own:
+
+- `pose2d(video)` – normalized image-space landmarks
+- `pose3d(video)` – MediaPipe world landmarks
+- `poseworld(pose2d, pose3d)` – PnP + floor-stabilized world coordinates
+- `inverse_kinematics(trc, model)`
+- `inverse_dynamics(ik_mot, model, external_forces)`
+- `external_forces([...])` – friendly force specs, including a dumbbell helper
+
+## Installation
+
+### Core package
+
+```bash
+pip install monomech
+```
+
+### Pose extraction extra
+
+```bash
+pip install "monomech[pose,viz]"
+```
+
+### OpenSim-enabled environment
+
+OpenSim is intentionally treated as an **optional runtime** because it is typically distributed through conda rather than PyPI.
+
+```bash
+conda install -c opensim-org opensim
+pip install "monomech[pose,viz]"
+```
+
+## Files written by default
+
+For each trial, MonoMech writes:
+
+- `pose2d.csv`
+- `pose3d.csv`
+- `pose_confidence.csv`
+- `poseworld.csv`
+- `camera.csv`
+- `poseworld.trc`
+- `ik.mot` and `ik.csv` when IK is run
+- `external_loads.mot` and `ExternalLoads.xml` when forces are added
+- `id.sto` and `id.csv` when inverse dynamics is run
+- `pose_analysis.html`
+- `rig_viewer.html`
+
+## Notebook-friendly results
+
+Each stage returns a `StageResult` with:
+
+- `.dataframe`
+- `.artifacts`
+- `.metadata`
+- `.inspect()`
+- `.to_csv()`
+- `_repr_html_()` for a quick preview in Jupyter
+
+## Caveats
+
+- OpenSim availability differs by environment; IK/ID will raise a clean error if the `opensim` Python module is unavailable.
+- The FBX viewer is configurable. A default rig mapping is included and can be overridden for your asset.
+- Single-camera kinetics still depend on modeling assumptions. MonoMech makes those assumptions explicit in the metadata and exported files.
+
+See the `docs/` folder and example notebooks for end-to-end usage.

monomech-0.1.0/README.md

@@ -0,0 +1,105 @@
+# MonoMech
+
+**MonoMech** is a single-camera-to-biomechanics Python library for turning one video path or a list of video paths into inspectable kinematics and kinetics.
+
+It is designed to be:
+
+- **modular**: each stage is callable on its own
+- **notebook friendly**: every stage returns a dataframe-centric result object and optional HTML visualization
+- **OpenSim aware**: exports `TRC`, `MOT`, `STO`, `CSV`, and builds inverse-kinematics / inverse-dynamics workflows
+- **publishable**: ships with `pyproject.toml`, docs, tests, conda recipe, and example notebooks
+
+## Main ideas
+
+```python
+from monomech import MonoMechPipeline, PipelineConfig, dumbbell_force
+
+pipeline = MonoMechPipeline(
+    PipelineConfig(output_root="outputs")
+)
+
+trial = pipeline.run(
+    "subject01_squat.mp4",
+    model_path="examples/assets/Mediapipe_Model.osim",
+    fbx_path="examples/assets/MovisionModel.fbx",
+    external_forces=[
+        dumbbell_force(side="right", mass_kg=12.5, point_in_body=(0.0, -0.02, 0.0))
+    ],
+)
+
+trial.pose2d.inspect().head()
+trial.poseworld.inspect().head()
+trial.inverse_kinematics.inspect().head()
+trial.inverse_dynamics.inspect().head()
+trial.visualizations["pose_analysis"]
+trial.visualizations["rig_viewer"]
+```
+
+## Stage-by-stage API
+
+Each stage can also run on its own:
+
+- `pose2d(video)` – normalized image-space landmarks
+- `pose3d(video)` – MediaPipe world landmarks
+- `poseworld(pose2d, pose3d)` – PnP + floor-stabilized world coordinates
+- `inverse_kinematics(trc, model)`
+- `inverse_dynamics(ik_mot, model, external_forces)`
+- `external_forces([...])` – friendly force specs, including a dumbbell helper
+
+## Installation
+
+### Core package
+
+```bash
+pip install monomech
+```
+
+### Pose extraction extra
+
+```bash
+pip install "monomech[pose,viz]"
+```
+
+### OpenSim-enabled environment
+
+OpenSim is intentionally treated as an **optional runtime** because it is typically distributed through conda rather than PyPI.
+
+```bash
+conda install -c opensim-org opensim
+pip install "monomech[pose,viz]"
+```
+
+## Files written by default
+
+For each trial, MonoMech writes:
+
+- `pose2d.csv`
+- `pose3d.csv`
+- `pose_confidence.csv`
+- `poseworld.csv`
+- `camera.csv`
+- `poseworld.trc`
+- `ik.mot` and `ik.csv` when IK is run
+- `external_loads.mot` and `ExternalLoads.xml` when forces are added
+- `id.sto` and `id.csv` when inverse dynamics is run
+- `pose_analysis.html`
+- `rig_viewer.html`
+
+## Notebook-friendly results
+
+Each stage returns a `StageResult` with:
+
+- `.dataframe`
+- `.artifacts`
+- `.metadata`
+- `.inspect()`
+- `.to_csv()`
+- `_repr_html_()` for a quick preview in Jupyter
+
+## Caveats
+
+- OpenSim availability differs by environment; IK/ID will raise a clean error if the `opensim` Python module is unavailable.
+- The FBX viewer is configurable. A default rig mapping is included and can be overridden for your asset.
+- Single-camera kinetics still depend on modeling assumptions. MonoMech makes those assumptions explicit in the metadata and exported files.
+
+See the `docs/` folder and example notebooks for end-to-end usage.

monomech-0.1.0/docs/api.md

@@ -0,0 +1,17 @@
+# API
+
+## Top-level objects
+
+- `MonoMechPipeline`
+- `PipelineConfig`
+- `PoseExtractionConfig`
+- `PoseWorldConfig`
+- `OpenSimConfig`
+- `ExternalForceSpec`
+- `dumbbell_force`
+
+## Results
+
+- `StageResult`
+- `TrialResult`
+- `BatchResult`

monomech-0.1.0/docs/getting-started.md

@@ -0,0 +1,34 @@
+# Getting started
+
+## One file
+
+```python
+from monomech import MonoMechPipeline, PipelineConfig
+
+pipeline = MonoMechPipeline(PipelineConfig(output_root="outputs"))
+trial = pipeline.run(
+    "trial.mp4",
+    model_path="model.osim",
+)
+```
+
+## Multiple files
+
+```python
+trials = pipeline.run_many(
+    ["walk.mp4", "squat.mp4", "curl.mp4"],
+    model_path="model.osim",
+)
+```
+
+## Add a dumbbell load
+
+```python
+from monomech import dumbbell_force
+
+trial = pipeline.run(
+    "curl.mp4",
+    model_path="model.osim",
+    external_forces=[dumbbell_force(side="right", mass_kg=10.0)],
+)
+```

monomech-0.1.0/docs/index.md

@@ -0,0 +1,14 @@
+# MonoMech
+
+MonoMech is a single-camera biomechanics package built around modular dataframe-first stages:
+
+1. **pose2d**
+2. **pose3d**
+3. **poseworld**
+4. **TRC export**
+5. **inverse kinematics**
+6. **external loads**
+7. **inverse dynamics**
+8. **HTML notebook visualizations**
+
+Every stage is inspectable and exportable.

monomech-0.1.0/docs/notebooks.md

@@ -0,0 +1,9 @@
+# Notebook support
+
+MonoMech ships with HTML-first notebook visualizers:
+
+- `trial.poseworld.inspect()`
+- `trial.pose_analysis_html()`
+- `trial.rig_viewer_html()`
+
+These return or embed HTML using Plotly and Three.js.

monomech-0.1.0/docs/packaging.md

@@ -0,0 +1,26 @@
+# Packaging
+
+The repository includes:
+
+- `pyproject.toml` for PyPI builds
+- `conda/meta.yaml` for conda packaging
+- `environment.yml` for reproducible setup
+- `mkdocs.yml` for docs generation
+
+## Build
+
+```bash
+python -m build
+```
+
+## Upload to PyPI
+
+```bash
+twine upload dist/*
+```
+
+## Build a conda package
+
+```bash
+conda build conda
+```

monomech-0.1.0/examples/MonoMech_External_Forces.ipynb

@@ -0,0 +1,42 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# MonoMech External Forces\n",
+        "A dumbbell load applied to the right hand.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "execution_count": null,
+      "outputs": [],
+      "source": [
+        "from monomech import MonoMechPipeline, PipelineConfig, dumbbell_force\n",
+        "pipeline = MonoMechPipeline(PipelineConfig(output_root='outputs'))\n",
+        "trial = pipeline.run(\n",
+        "    'curl.mp4',\n",
+        "    model_path='examples/assets/Mediapipe_Model.osim',\n",
+        "    fbx_path='examples/assets/MovisionModel.fbx',\n",
+        "    external_forces=[dumbbell_force(side='right', mass_kg=12.5)],\n",
+        ")\n",
+        "trial.inverse_dynamics.inspect().head()\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.11"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

monomech-0.1.0/examples/MonoMech_Getting_Started.ipynb

@@ -0,0 +1,59 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# MonoMech Getting Started\n",
+        "This notebook runs the full pipeline and previews dataframe outputs.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "execution_count": null,
+      "outputs": [],
+      "source": [
+        "from monomech import MonoMechPipeline, PipelineConfig\n",
+        "pipeline = MonoMechPipeline(PipelineConfig(output_root='outputs'))\n",
+        "trial = pipeline.run(\n",
+        "    'trial.mp4',\n",
+        "    model_path='examples/assets/Mediapipe_Model.osim',\n",
+        "    fbx_path='examples/assets/MovisionModel.fbx',\n",
+        ")\n",
+        "trial.summary()\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "execution_count": null,
+      "outputs": [],
+      "source": [
+        "trial.pose2d.inspect().head()\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "execution_count": null,
+      "outputs": [],
+      "source": [
+        "trial.visualizations\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.11"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}