# `veux`
<img align="left" src="https://stairlab.github.io/opensees-gallery/examples/shellframe/ShellFrame.png" width="350px" alt="SEES Logo">
**Highly efficient and portable finite element visualization framework**
<br>
<div style="align:center">
[](https://doi.org/10.5281/zenodo.13367076)
[](https://pypi.python.org/pypi/veux)
</div>
`veux` is a finite element rendering library that leverages modern
web technologies to produce sharable, efficient, and detailed renderings.
--------------------------------------------------------------------
<br>
`veux` is a finite element rendering library that leverages modern
web technologies to produce sharable, efficient, and detailed renderings.
Unlike most tools that only provide temporary visualization, `veux` generates
persistent 3D models that can be stored in files, shared with colleagues, and
viewed with any standard 3D model viewer. This means anyone can interact with
the renderings without needing to install specialized software or even Python.
Simply open the 3D object with your computer’s 3D viewer (e.g., 3D Viewer on
Windows) or load it into a free online viewer in like [gltf-viewer](https://gltf-viewer.donmccurdy.com/).
Documentation is currently under development.
## Features
- **Detailed** Render frames with extruded cross sections
- **Persistence**: Save your finite element visualizations as persistent 3D models that can be revisited and analyzed at any time.
- **Portability**: Share your models effortlessly with colleagues, enabling seamless collaboration and review.
- **Accessibility**: View and interact with the models using any standard 3D model viewer, eliminating the need for specialized software or Python installation.
- **Versatility**: A wide selection of rendering backends and output file types, including
optimized 3D web formats like `.glb`. Generated 3D models can be loaded directly into programs like PowerPoint and animated.
- Correctly render models that treat both `y` or `z` as the
vertical coordinate.
--------------------------------------------------------------------
## Getting Started
To install `veux` run:
```shell
pip install veux
```
### Python Interface
To render a model directly from Python, use the `veux.render` function:
```python
artist = veux.render(model, canvas=canvas)
```
- **model**: the `model` parameter can be of several types
- `str` (string) variables are treated like file paths. Supported files are `.json` and `.tcl`
- `dict` variables are treated
- [`Model`](https://stairlab.github.io/OpenSeesDocumentation/user/manual/model/model_class.html) variables from the [`sees`](https://pypi.org/project/sees) Python package can be passed directly
- **canvas**: The `canvas` parameter is a string which indicates which "backend" technology to use. The options are:
- `"gltf"` is the default canvas and produces the highest quality renderings. You can save renderings drawn by this backend to either `.html` or `.glb` files. `.glb` files are preferred as they are a natural format for 3D objects and can be viewed by standard 3D viewing applications.
- `"plotly"` is best for model debugging as it is able to embed model details like node/element numbers and properties with hover annotations. However, the renderings produced by this backend dont look quite as good as with `gltf`.
- `"matplotlib"`: can be used to programatically create `.png` files.
Once the `artist` is created, the rendering can either be displayed or saved to a file. Each `canvas` supports slightly different options:
- **viewing** To view a rendering that is generated either with `canvas="gltf"` or `canvas="plotly"`, use the `veux.serve()` function:
```python
veux.serve(artist)
```
After running you will see a message like the following printed
to your terminal:
```
Bottle v0.13.1 server starting up (using WSGIRefServer())...
Listening on http://localhost:8081/
Hit Ctrl-C to quit.
```
Paste the URL from this message (eg, http://localhost:8081) into
the address bar of a browser and an interactive rendering will
appear.
- **saving** Use the `artist`'s `save()` method to write the rendering to a file. The file type depends on the canvas:
- with `canvas="gltf"`, files are saved in the glTF format with extension `.glb`:
```python
...
artist.save("model.glb")
```
- with `canvas="plotly"`, files are saved in to HTML:
```python
...
artist.save("model.html")
```
- with `canvas="matplotlib"`, files are saved in as PNGs:
```python
...
artist.save("model.png")
```
Note, however, that renderings produced by the `"matplotlib"` canvas are generally very poor quality.
For high quality images, use the `"gltf"` canvas and take screen captures.
### Command Line Interface
To create a rendering, execute the following command from the anaconda prompt (after activating the appropriate environment):
```shell
python -m veux model.json -o model.html
```
where `model.json` is a JSON file generated from executing the following OpenSees command:
```tcl
print -JSON model.json
```
If you omit the `-o <file.html>` portion, it will plot immediately in a new
window. You can also use a `.png` extension to save a static image file, as
opposed to the interactive html.
> **Note** Printing depends on the JSON output of a model. Several materials and
> elements in the OpenSeesPy and upstream OpenSees implementations do not
> correctly print to JSON. For the most reliable results, use the
> [`opensees`](https://pypi.org/project/opensees) package.
By default, the rendering treats the $y$ coordinate as vertical.
In order to manually control this behavior, pass the option
`--vert 3` to render model $z$ vertically, or `--vert 2` to render model $y$ vertically.
If the [`opensees`](https://pypi.org/project/opensees) package is installed,
you can directly render a Tcl script without first printing to JSON,
by just passing a Tcl script instead of the JSON file:
```shell
python -m veux model.tcl -o model.html
```
To plot an elevation (`elev`) plan (`plan`) or section (`sect`) view, run:
```shell
python -m veux model.json --view elev
```
and add `-o <file.extension>` as appropriate.
To see the help page run
```shell
python -m veux --help
```
<br>
## Related Links
See also
- [`sees`](https://github.com/claudioperez/OpenSeesRT)
- [`osmg`](https://pypi.org/project/osmg)
- [`mdof`](https://pypi.org/project/mdof)
- [`sdof`](https://pypi.org/project/sdof)
The `veux` packages was used to generate figures for the following publications:
- *On nonlinear geometric transformations of finite elements* [doi: 10.1002/nme.7506](https://doi.org/10.1002/nme.7506)
<!--
Similar packages for OpenSees rendering include:
- [`vfo`](https://vfo.readthedocs.io/en/latest/)
- [`opsvis`](https://opsvis.readthedocs.io/en/latest/index.html)
Other
- [`fapp`](https://github.com/wcfrobert/fapp)
-->
## Gallery
| | |
| :---------------: | :---------------: |
| ![][glry-0001] | ![][glry-0003] |
| ![][glry-0002] | ![][glry-0005] |
[glry-0001]: <https://stairlab.github.io/opensees-gallery/gallery/cablestayed02/CableStayed02.png>
[view-0001]: <https://stairlab.github.io/opensees-gallery/gallery/cablestayed02/CableStayed02.png>
[glry-0002]: <https://stairlab.github.io/opensees-gallery/examples/example7/safeway_hu11201694704832599949.png>
[view-0002]: <https://stairlab.github.io/opensees-gallery/examples/example7/safeway_hu11201694704832599949.png>
[glry-0003]: <https://stairlab.github.io/opensees-gallery/examples/shellframe/ShellFrame_hu5013315635971397841.png>
[view-0003]: <https://stairlab.github.io/opensees-gallery/examples/shellframe/ShellFrame_hu5013315635971397841.png>
[glry-0005]: <https://raw.githubusercontent.com/STAIRlab/veux/master/docs/figures/shellframe01.png>
[view-0005]: <https://raw.githubusercontent.com/STAIRlab/veux/master/docs/figures/shellframe01.png>
## Support
<table align="center">
<tr>
<td>
<a href="https://peer.berkeley.edu">
<img src="https://raw.githubusercontent.com/claudioperez/sdof/master/docs/assets/peer-black-300.png"
alt="PEER Logo" width="100"/>
</a>
</td>
<td>
<a href="https://dot.ca.gov/">
<img src="https://raw.githubusercontent.com/claudioperez/sdof/master/docs/assets/Caltrans.svg.png"
alt="Caltrans Logo" width="100"/>
</a>
</td>
<td>
<a href="https://stairlab.berkeley.edu/software/">
<img src="https://raw.githubusercontent.com/claudioperez/sdof/master/docs/assets/stairlab.svg"
alt="STAIRlab Logo" width="100"/>
</a>
</td>
</tr>
</table>
Raw data
{
"_id": null,
"home_page": null,
"name": "veux",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "visualization, rendering, seismic, opensees, nonlinear, post-processing, finite-element-analysis, glTF",
"author": null,
"author_email": "\"Claudio M. Perez\" <50180406+claudioperez@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/fb/df/a9d0924c941c3572d4f92ef030aa092993fdb912751d6868bc0f4a84fe2d/veux-0.0.5.tar.gz",
"platform": null,
"description": "# `veux`\n\n<img align=\"left\" src=\"https://stairlab.github.io/opensees-gallery/examples/shellframe/ShellFrame.png\" width=\"350px\" alt=\"SEES Logo\">\n\n\n**Highly efficient and portable finite element visualization framework**\n\n<br>\n\n\n<div style=\"align:center\">\n\n[](https://doi.org/10.5281/zenodo.13367076)\n[](https://pypi.python.org/pypi/veux)\n\n</div>\n\n`veux` is a finite element rendering library that leverages modern \nweb technologies to produce sharable, efficient, and detailed renderings.\n\n\n-------------------------------------------------------------------- \n\n<br>\n\n`veux` is a finite element rendering library that leverages modern \nweb technologies to produce sharable, efficient, and detailed renderings.\nUnlike most tools that only provide temporary visualization, `veux` generates\npersistent 3D models that can be stored in files, shared with colleagues, and\nviewed with any standard 3D model viewer. This means anyone can interact with\nthe renderings without needing to install specialized software or even Python.\nSimply open the 3D object with your computer\u2019s 3D viewer (e.g., 3D Viewer on\nWindows) or load it into a free online viewer in like [gltf-viewer](https://gltf-viewer.donmccurdy.com/).\n\nDocumentation is currently under development.\n\n## Features\n\n- **Detailed** Render frames with extruded cross sections\n- **Persistence**: Save your finite element visualizations as persistent 3D models that can be revisited and analyzed at any time.\n- **Portability**: Share your models effortlessly with colleagues, enabling seamless collaboration and review.\n- **Accessibility**: View and interact with the models using any standard 3D model viewer, eliminating the need for specialized software or Python installation.\n- **Versatility**: A wide selection of rendering backends and output file types, including \n optimized 3D web formats like `.glb`. Generated 3D models can be loaded directly into programs like PowerPoint and animated.\n- Correctly render models that treat both `y` or `z` as the\n vertical coordinate.\n\n-------------------------------------------------------------------- \n\n\n## Getting Started\n\nTo install `veux` run:\n\n```shell\npip install veux\n```\n\n### Python Interface\n\nTo render a model directly from Python, use the `veux.render` function:\n\n```python\nartist = veux.render(model, canvas=canvas)\n```\n\n- **model**: the `model` parameter can be of several types\n - `str` (string) variables are treated like file paths. Supported files are `.json` and `.tcl`\n - `dict` variables are treated\n - [`Model`](https://stairlab.github.io/OpenSeesDocumentation/user/manual/model/model_class.html) variables from the [`sees`](https://pypi.org/project/sees) Python package can be passed directly\n- **canvas**: The `canvas` parameter is a string which indicates which \"backend\" technology to use. The options are:\n - `\"gltf\"` is the default canvas and produces the highest quality renderings. You can save renderings drawn by this backend to either `.html` or `.glb` files. `.glb` files are preferred as they are a natural format for 3D objects and can be viewed by standard 3D viewing applications.\n - `\"plotly\"` is best for model debugging as it is able to embed model details like node/element numbers and properties with hover annotations. However, the renderings produced by this backend dont look quite as good as with `gltf`.\n - `\"matplotlib\"`: can be used to programatically create `.png` files.\n\nOnce the `artist` is created, the rendering can either be displayed or saved to a file. Each `canvas` supports slightly different options:\n- **viewing** To view a rendering that is generated either with `canvas=\"gltf\"` or `canvas=\"plotly\"`, use the `veux.serve()` function:\n ```python\n veux.serve(artist)\n ```\n After running you will see a message like the following printed\n to your terminal:\n ```\n Bottle v0.13.1 server starting up (using WSGIRefServer())...\n Listening on http://localhost:8081/\n Hit Ctrl-C to quit.\n ```\n Paste the URL from this message (eg, http://localhost:8081) into\n the address bar of a browser and an interactive rendering will\n appear.\n\n- **saving** Use the `artist`'s `save()` method to write the rendering to a file. The file type depends on the canvas:\n - with `canvas=\"gltf\"`, files are saved in the glTF format with extension `.glb`:\n ```python\n ...\n artist.save(\"model.glb\")\n ```\n - with `canvas=\"plotly\"`, files are saved in to HTML:\n ```python\n ...\n artist.save(\"model.html\")\n ```\n - with `canvas=\"matplotlib\"`, files are saved in as PNGs:\n ```python\n ...\n artist.save(\"model.png\")\n ```\n Note, however, that renderings produced by the `\"matplotlib\"` canvas are generally very poor quality. \n For high quality images, use the `\"gltf\"` canvas and take screen captures.\n\n\n### Command Line Interface\n\nTo create a rendering, execute the following command from the anaconda prompt (after activating the appropriate environment):\n\n```shell\npython -m veux model.json -o model.html\n```\n\nwhere `model.json` is a JSON file generated from executing the following OpenSees command:\n\n```tcl\nprint -JSON model.json\n```\n\nIf you omit the `-o <file.html>` portion, it will plot immediately in a new\nwindow. You can also use a `.png` extension to save a static image file, as\nopposed to the interactive html.\n\n> **Note** Printing depends on the JSON output of a model. Several materials and\n> elements in the OpenSeesPy and upstream OpenSees implementations do not\n> correctly print to JSON. For the most reliable results, use the\n> [`opensees`](https://pypi.org/project/opensees) package.\n\nBy default, the rendering treats the $y$ coordinate as vertical.\nIn order to manually control this behavior, pass the option \n`--vert 3` to render model $z$ vertically, or `--vert 2` to render model $y$ vertically.\n\nIf the [`opensees`](https://pypi.org/project/opensees) package is installed,\nyou can directly render a Tcl script without first printing to JSON, \nby just passing a Tcl script instead of the JSON file:\n\n```shell\npython -m veux model.tcl -o model.html\n```\n\nTo plot an elevation (`elev`) plan (`plan`) or section (`sect`) view, run:\n\n```shell\npython -m veux model.json --view elev\n```\n\nand add `-o <file.extension>` as appropriate.\n\nTo see the help page run\n\n```shell\npython -m veux --help\n```\n\n<br>\n\n## Related Links\n\nSee also\n\n- [`sees`](https://github.com/claudioperez/OpenSeesRT)\n- [`osmg`](https://pypi.org/project/osmg)\n- [`mdof`](https://pypi.org/project/mdof)\n- [`sdof`](https://pypi.org/project/sdof)\n\n\nThe `veux` packages was used to generate figures for the following publications:\n\n- *On nonlinear geometric transformations of finite elements* [doi: 10.1002/nme.7506](https://doi.org/10.1002/nme.7506)\n\n<!-- \nSimilar packages for OpenSees rendering include:\n\n- [`vfo`](https://vfo.readthedocs.io/en/latest/)\n- [`opsvis`](https://opsvis.readthedocs.io/en/latest/index.html)\n\nOther\n\n- [`fapp`](https://github.com/wcfrobert/fapp) \n-->\n\n## Gallery\n\n\n| | |\n| :---------------: | :---------------: |\n| ![][glry-0001] | ![][glry-0003] |\n| ![][glry-0002] | ![][glry-0005] |\n\n\n[glry-0001]: <https://stairlab.github.io/opensees-gallery/gallery/cablestayed02/CableStayed02.png>\n[view-0001]: <https://stairlab.github.io/opensees-gallery/gallery/cablestayed02/CableStayed02.png>\n\n[glry-0002]: <https://stairlab.github.io/opensees-gallery/examples/example7/safeway_hu11201694704832599949.png>\n[view-0002]: <https://stairlab.github.io/opensees-gallery/examples/example7/safeway_hu11201694704832599949.png>\n\n[glry-0003]: <https://stairlab.github.io/opensees-gallery/examples/shellframe/ShellFrame_hu5013315635971397841.png>\n[view-0003]: <https://stairlab.github.io/opensees-gallery/examples/shellframe/ShellFrame_hu5013315635971397841.png>\n\n[glry-0005]: <https://raw.githubusercontent.com/STAIRlab/veux/master/docs/figures/shellframe01.png>\n[view-0005]: <https://raw.githubusercontent.com/STAIRlab/veux/master/docs/figures/shellframe01.png>\n\n\n## Support\n\n<table align=\"center\">\n<tr>\n\n <td>\n <a href=\"https://peer.berkeley.edu\">\n <img src=\"https://raw.githubusercontent.com/claudioperez/sdof/master/docs/assets/peer-black-300.png\"\n alt=\"PEER Logo\" width=\"100\"/>\n </a>\n </td>\n\n <td>\n <a href=\"https://dot.ca.gov/\">\n <img src=\"https://raw.githubusercontent.com/claudioperez/sdof/master/docs/assets/Caltrans.svg.png\"\n alt=\"Caltrans Logo\" width=\"100\"/>\n </a>\n </td>\n\n <td>\n <a href=\"https://stairlab.berkeley.edu/software/\">\n <img src=\"https://raw.githubusercontent.com/claudioperez/sdof/master/docs/assets/stairlab.svg\"\n alt=\"STAIRlab Logo\" width=\"100\"/>\n </a>\n </td>\n \n </tr>\n</table>\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Finite element visualization with GPU support",
"version": "0.0.5",
"project_urls": {
"Documentation": "https://stairlab.berkeley.edu/software/veux",
"Examples": "https://gallery.stairlab.io/",
"Repository": "https://github.com/STAIRLab/veux"
},
"split_keywords": [
"visualization",
" rendering",
" seismic",
" opensees",
" nonlinear",
" post-processing",
" finite-element-analysis",
" gltf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "09525553e89486e38469b05cb250cedeef5b1c1277cac5419a5a7594e52dec97",
"md5": "b0e314d0581319d21d0cd5d9fb3e1c8c",
"sha256": "dddb1621c3ea7d93a92d29bcaedb8194d341f0835b641d7cb28503d222b0967e"
},
"downloads": -1,
"filename": "veux-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b0e314d0581319d21d0cd5d9fb3e1c8c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 98736,
"upload_time": "2025-01-10T01:27:10",
"upload_time_iso_8601": "2025-01-10T01:27:10.019734Z",
"url": "https://files.pythonhosted.org/packages/09/52/5553e89486e38469b05cb250cedeef5b1c1277cac5419a5a7594e52dec97/veux-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fbdfa9d0924c941c3572d4f92ef030aa092993fdb912751d6868bc0f4a84fe2d",
"md5": "835b35ca8739ab0d292a1d5366b94064",
"sha256": "638fb82c6a304d67f37a72163eaae3c7b480eb401bc259dea4bc04b4d676c647"
},
"downloads": -1,
"filename": "veux-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "835b35ca8739ab0d292a1d5366b94064",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 91961,
"upload_time": "2025-01-10T01:27:12",
"upload_time_iso_8601": "2025-01-10T01:27:12.579987Z",
"url": "https://files.pythonhosted.org/packages/fb/df/a9d0924c941c3572d4f92ef030aa092993fdb912751d6868bc0f4a84fe2d/veux-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-10 01:27:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "STAIRLab",
"github_project": "veux",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "veux"
}
JSON
