{"id":34552894,"url":"https://github.com/pyomeca/bioviz","last_synced_at":"2025-12-24T08:05:09.758Z","repository":{"id":41871999,"uuid":"150156937","full_name":"pyomeca/bioviz","owner":"pyomeca","description":"Biorbd visualization toolkit","archived":false,"fork":false,"pushed_at":"2025-12-18T20:57:59.000Z","size":5067,"stargazers_count":20,"open_issues_count":14,"forks_count":26,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-12-21T22:10:22.889Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyomeca.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-09-24T19:27:09.000Z","updated_at":"2025-12-18T20:55:54.000Z","dependencies_parsed_at":"2023-02-14T22:31:02.995Z","dependency_job_id":"4d92a611-6d68-475f-9ab7-a99f3b0cb80a","html_url":"https://github.com/pyomeca/bioviz","commit_stats":null,"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/pyomeca/bioviz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyomeca%2Fbioviz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyomeca%2Fbioviz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyomeca%2Fbioviz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyomeca%2Fbioviz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyomeca","download_url":"https://codeload.github.com/pyomeca/bioviz/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyomeca%2Fbioviz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27998473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T08:04:30.474Z","updated_at":"2025-12-24T08:05:09.744Z","avatar_url":"https://github.com/pyomeca.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg\n      src=\"https://github.com/pyomeca/biorbd_design/blob/main/logo_png/bioviz_full.png\"\n      alt=\"logo\"\n    /\u003e\n\u003c/p\u003e\n\n`bioviz` is the Python visualizer of the `biorbd` biomechanical library (https://github.com/pyomeca/biorbd). \nThis library provides filters and analyses for biomechanical data in C++, Python and MATLAB languages.\n\nHowever, there is no built-in visualization system, therefore this Python module! \nIt allow for a beautiful, yet simplistic visualization of the model in static or dynamic poses. \n\nSo, without further ado, let's remove `biorbd` from the darkness!\n\n\u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-success\" alt=\"License\"/\u003e\u003c/a\u003e\n\n# How to install\nThere are two main ways to install `bioviz` on your computer: installing the binaries from Anaconda (easiest) or installing from the sources (requires to download the sources)\n\n## Anaconda (For Windows, Linux and Mac)\nThe easiest way to install `bioviz` is to download the binaries from Anaconda (https://anaconda.org/) repositories. The project is hosted on the conda-forge channel (https://anaconda.org/conda-forge/bioviz).\n\nAfter having installed properly an anaconda client [my suggestion would be Miniconda (https://conda.io/miniconda.html)] and loaded the desired environment to install `biorbd` in, just type the following command:\n```bash\nconda install -c conda-forge bioviz\n```\nPlease note that this will install all the dependencies of `bioviz` *including* `biorbd`. If you are a developer of `biorbd`, this is therefore not the prefered method of installation since the `biorbd` binaries from conda-forge may interfere with those you create. \n\n## Installing from the sources\nTo install from the sources, you simply have to download the source, navigate to the root folder and (assuming your conda environment is loaded if neede) type the following command\n```bash\npython setup.py install\n```\nPlease note that this method will not install the dependencies for you, therefore you will have to install them manually, *including* `biorbd`. Moreover, the *setuptools* dependencies must be installed prior to the installation in order for it to work.\n\n## Dependencies\n`bioviz` relies on several libraries. The most obvious one is `biorbd`, but *pyomeca* is also requires and some others. The first hand dependencies (meaning that some dependencies may require other libraries themselves) are: pandas (https://pandas.pydata.org/), numpy (https://numpy.org/), scipy (https://scipy.org/), matplotlib (https://matplotlib.org/), vtk (https://vtk.org/), PyQt (https://www.riverbankcomputing.com/software/pyqt), biorbd (https://github.com/pyomeca/biorbd), pyomeca (https://github.com/pyomeca/pyomeca) and ezc3d (https://github.com/pyomeca/ezc3d). All these can manually be install using (assuming the anaconda environment is loaded if needed) `pip3` command or the Anaconda's following command.\n```bash\nconda install pandas numpy scipy matplotlib vtk pyqt biorbd pyomeca ezc3d -cconda-forge\n```\n\n# How to use\n`bioviz` is being as minimalistic as possible in order to make it easy to use. Basically, one has to  `import` the library, load the model and you are good to go. The following code shows how to launch the software without any other options.\n```Python\nimport bioviz\nbioviz.Viz('path/to/model.bioMod').exec()\n```\nPlease note that the `exec()` method won't return the hand until the window is closed. If for some reasons, one wants to keep control of the code, they can manually update the GUI using the following snippet. The while loop will then exit when the window is closed. \n\n```Python\nimport bioviz\nbiorbd_viz = bioviz.Viz('path/to/model.bioMod')\nwhile biorbd_viz.vtk_window.is_active:\n    # Do some stuff...\n    biorbd_viz.refresh_window()\n```\n\n## Interacting with the model\n\nThe interaction with the model is fairly easy. Using the sliders on the left hand side of the main window, you can change the position of the model, according to the degrees-of-freedom the model has. Pressing the reset button replaces the model at its default attitude. \n\n## Options at loading\nIf you are interacting with the model using `biorbd`, you may want to link that model you are interacting with and the one used by `bioviz`. To do so, you can actually pass the model using the `loaded_model` parameter of the constructor, like so.\n```Python\nimport biorbd\nimport bioviz\nmodel = biorbd.Model('path/to/model.bioMod')\n# Do some stuff with you model...\nbioviz.Viz(loaded_model=model).exec()\n```\n\nThe element that are shown on the model can be turned *off* at the loading of the window. The elements are: the *mesh of the segments*, the *global/segments center of mass*, the *global/segments reference frame*, the *skin markers*, the *muscles*, the *analyses panel*. The following code turns everything *off*, which is a bit useless since nothing will be shown.\n```Python\nimport bioviz\nbioviz.Viz('path/to/model.bioMod', \n    show_meshes=False,\n    show_global_center_of_mass=False, show_segments_center_of_mass=False,\n    show_global_ref_frame=False, show_local_ref_frame=False, \n    show_markers=False, \n    show_muscles=False, \n    show_analyses_panel=False\n).exec()\n```\n\n## Loading a movement\n\n### From the GUI\n\nFor loading a movement that the model will perform, one has simply to click on the *Load movement* button and load the previously save movement file. The file must be a numpy array of $n_{DoF} \\times n_{Frames}$ matrix.\n\n### From the command line\n\nA second method of attaching a movement to the model is to manually attach it to the GUI. To do so, one simply has to call the `load_movement` function then either call the `exec` function, or manually update the GUI. The following code shows these two different methods (depending if `manually_animate` is set to `True` or `False`. Please note that the `exec()` way is preferred. \n\n```Python\nimport numpy as np\nimport bioviz\nmanually_animate = False\n\n# Load the model\nbiorbd_viz = bioviz.Viz('path/to/model.bioMod')\n\n# Create a movement \nn_frames = 200\nall_q = np.zeros((biorbd_viz.nQ, n_frames))\nall_q[4, :] = np.linspace(0, np.pi / 2, n_frames)\n\n# Animate the model\nif manually_animate:\n    i = 0\n    while biorbd_viz.vtk_window.is_active:\n        biorbd_viz.set_q(all_q[i, :])\n        i = (i+1) % n_frames\nelse:\n    biorbd_viz.load_movement(all_q)\n    biorbd_viz.exec()\n\n```\n\n## Loading external forces\n\n### From the command line\n\n```Python\nimport numpy as np\nimport bioviz\n\n# Load the model\nbiorbd_viz = bioviz.Viz('path/to/model.bioMod')\n\n# Create a movement\nn_frames = 200\nall_q = np.zeros((biorbd_viz.nQ, n_frames))\nall_q[4, :] = np.linspace(0, np.pi / 2, n_frames)\n\nf_ext = np.zeros((1,6,n_frames))\n# fill the origin of the external force\nf_ext[0,:3,:] = np.linspace(np.zeros(3), np.ones(3) * 0.1, n_frames).T\n# fill the location of the tip of the arrow\nf_ext[0,3:,:] = np.linspace(np.ones(3) * 0.2, np.ones(3) * 0.25, n_frames).T\n\n# Animate the model\nbiorbd_viz.load_movement(all_q)\nbiorbd_viz.load_experimental_forces(f_ext, segments=None, normalization_ratio=0.2)\nbiorbd_viz.exec()\n```\n\n## Analyses panel\n\nSlowly but surely, it is plan that the visualizer will become a proper GUI of `biorbd`, allowing for instance to interactively modify a *bioMod* file or to perform biomechanical analyses. For now, there is one muscle analyses panel which is available. \n\n### Muscle analyses panel\nBy clicking on *Muscles* in the *Analyses* pane, the main window should expand showing a simple muscle analyses panel. In this panel you can select the muscle to plot and the DoF (degree-of-freedom) to run the analyses on. By default, the analyses are perform from $-\\pi$ to $\\pi$. The vertical bar shows the current position of the model. Changing the position's slider will automatically update the plots of the analyses. \n\nThe *muscle length* plot shows the length of the muscle over the range of the select DoF assuming every other DoFs are constant. \n\nThe *moment arm* plot shows the moment arm about the selected DoF over the range of the selected DoF assuming every other DoFs are constant.\n\nThe *passive forces* plot shows the forces of the passive element of the muscle (assuming there are passive elements) over  the range of the selected DoF assuming every other DoFs are constant.\n\nFinally, the *active forces* plot shows the forces of the active element of the muscle (assuming there as active elements) over  the range of the selected DoF assuming every other DoFs are constant. Just next to the plot, there is a slider that activate the muscle (from 0% to 100% activation).\n\n# How to contribute\n\nYou are very welcome to contribute to the project! There are to main ways to contribute. \n\nThe first way is to actually code new features for `bioviz` such as new analyses modules. The easiest way to do so is to fork the project, make the modifications and then open a pull request to the main project. \n\nThe second way is to open issues to report bugs or to ask for new features. I am trying to be as reactive as possible, so don't hesitate to do so!\n\n# Cite\nIf you use `biorbd` (or its GUI `bioviz`), we would be grateful if you could cite it as follows:\n\n```\n@misc{Michaud2018biorbdViz,\n    author = {Michaud, Benjamin and Begon, Mickael},\n    title = {bioviz: A vizualization python toolbox for biorbd},\n    howpublished={Web page},\n    url = {https://github.com/pyomeca/bioviz},\n    year = {2018}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyomeca%2Fbioviz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyomeca%2Fbioviz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyomeca%2Fbioviz/lists"}