ply3d 0.1.0__tar.gz

ply3d-0.1.0/.gitignore

@@ -0,0 +1,106 @@
+.idea/
+*.swp
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+.virtual_documents
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# macos
+.DS_Store

ply3d-0.1.0/.gitlab-ci.yml

@@ -0,0 +1,70 @@
+image: continuumio/miniconda3:latest
+cache:
+    paths:
+        - .pip-cache/
+before_script:
+    - python --version
+    - pip install --upgrade pip
+    - pip install build twine
+
+stages:
+    - build
+    - test
+    - deploy
+
+variables:
+    PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"
+
+build:
+    stage: build
+    script:
+        - python -m build
+    artifacts:
+        paths:
+            - dist/
+    rules:
+        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+          when: manual
+        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+test:
+    stage: test
+    script:
+        - pip install dist/*.whl
+        - pip install pytest pytest-cov
+        - pytest -v test/
+    rules:
+        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+          when: manual
+        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+publish:
+    stage: deploy
+    script:
+        - TWINE_PASSWORD=${PYPI_TOKEN} TWINE_USERNAME=__token__ python -m twine upload --verbose --repository pypi dist/*
+    rules:
+        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+pages:
+    stage: deploy
+    script:
+        - apt-get update && apt-get install libxcursor-dev libgl1 libglx-mesa0 xvfb -y
+        - conda env create -f environment.yml
+        - source activate ply3d
+        - which pip
+        - export DISPLAY=:99.0
+        - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
+        - sleep 3
+        - pip install "mkdocs<=1.6.1" pymdown-extensions mkdocs-material "markdown-exec[ansi]"
+        - pip install "mkdocstrings[python]>=0.18" mkdocs-gen-files
+        - pip install mkdocs-literate-nav mkdocs-section-index
+        - pip install --no-deps .
+        - mkdocs build
+        - mv ./site public
+    artifacts:
+        paths:
+            - public
+    rules:
+        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+          when: manual
+        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

ply3d-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: ply3d
+Version: 0.1.0
+Summary: A Python library for manipulating PLY 3D geometries of multicellular tissues
+Author-email: Ross Carter <ross.carter@slcu.cam.ac.uk>, John Fozard <john.fozard@jic.ac.uk>, Guillaume Cerutti <guillaume.cerutti@ens-lyon.fr>
+Maintainer-email: Guillaume Cerutti <guillaume.cerutti@ens-lyon.fr>
+Project-URL: Homepage, https://gitlab.com/morphodynamics/mesh/ply3d_python
+Description-Content-Type: text/markdown
+Requires-Dist: matplotlib
+Requires-Dist: meshio
+Requires-Dist: pyvista[colormaps]
+Requires-Dist: tqdm
+
+# PLY 3D
+
+A Python library for manipulating PLY 3D geometries of multicellular tissues.
+
+## Motivation
+
+**PLY 3D** is an extension of the [PLY format](https://paulbourke.net/dataformats/ply/) introduced to store 3D meshes composed of interconnected, arbitrary polyhedral cells. While complying with the specifications of the original format, it introduces a number of specific syntaxes for mesh elements and properties.
+
+## Usage
+
+In Python, you can use the library to load and manipulate such meshes, and visualize them with all their properties using `pyvista`:
+
+```python
+from ply3d.ply_parser import read_ply_mesh
+
+mesh = read_ply_mesh("example_data/CylinderCells.ply")
+# mesh.vertices.points, mesh.volumes.face_indices, ...
+```
+
+```python
+from ply3d.vtk_export import unstructured_grid_from_mesh
+
+grid = unstructured_grid_from_mesh(mesh, elements_to_export=['volume'])
+```
+
+```python
+import pyvista as pv
+
+plotter = pv.Plotter()
+plotter.add_mesh(
+    grid.shrink(0.9), 
+    scalars='label', cmap='glasbey', clim=(0, 255), show_scalar_bar=False
+)
+plotter.show()
+```
+
+## Installation
+
+`ply3d` is available on PyPI (the Python Package Index) and can be installed by running:
+
+```bash
+pip install ply3d
+```
+
+## Documentation
+
+Please take a look at the [documentation](https://morphodynamics.gitlab.io/mesh/ply3d_python/) for more information on installation and usage
+
+
+## Authors
+
+This project is developed and maintained by the [Computational Morphodynamics Group](https://computationalmorphodynamics.org/); find out more about the [research groups](https://computationalmorphodynamics.org/research-groups/) involved.

ply3d-0.1.0/README.md

@@ -0,0 +1,52 @@
+# PLY 3D
+
+A Python library for manipulating PLY 3D geometries of multicellular tissues.
+
+## Motivation
+
+**PLY 3D** is an extension of the [PLY format](https://paulbourke.net/dataformats/ply/) introduced to store 3D meshes composed of interconnected, arbitrary polyhedral cells. While complying with the specifications of the original format, it introduces a number of specific syntaxes for mesh elements and properties.
+
+## Usage
+
+In Python, you can use the library to load and manipulate such meshes, and visualize them with all their properties using `pyvista`:
+
+```python
+from ply3d.ply_parser import read_ply_mesh
+
+mesh = read_ply_mesh("example_data/CylinderCells.ply")
+# mesh.vertices.points, mesh.volumes.face_indices, ...
+```
+
+```python
+from ply3d.vtk_export import unstructured_grid_from_mesh
+
+grid = unstructured_grid_from_mesh(mesh, elements_to_export=['volume'])
+```
+
+```python
+import pyvista as pv
+
+plotter = pv.Plotter()
+plotter.add_mesh(
+    grid.shrink(0.9), 
+    scalars='label', cmap='glasbey', clim=(0, 255), show_scalar_bar=False
+)
+plotter.show()
+```
+
+## Installation
+
+`ply3d` is available on PyPI (the Python Package Index) and can be installed by running:
+
+```bash
+pip install ply3d
+```
+
+## Documentation
+
+Please take a look at the [documentation](https://morphodynamics.gitlab.io/mesh/ply3d_python/) for more information on installation and usage
+
+
+## Authors
+
+This project is developed and maintained by the [Computational Morphodynamics Group](https://computationalmorphodynamics.org/); find out more about the [research groups](https://computationalmorphodynamics.org/research-groups/) involved.

ply3d-0.1.0/docs/gen_pages.py

@@ -0,0 +1,34 @@
+"""Generate the code reference pages."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent
+print(root)
+src = root / "src"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        print("::: " + identifier, file=fd)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

ply3d-0.1.0/docs/import.md

@@ -0,0 +1,63 @@
+# Importing Meshes
+
+There are dozens of existing mesh file formats that are used to store surfacic meshes or volumetric meshes, usually composed of standard volume elements (tetrahedra or hexahedra). Fortunately, the [`meshio`](https://pypi.org/project/meshio/) Python library almost supports them all!
+
+## Importing meshes using `meshio`
+
+The `ply3d` library relies on `meshio` to provide a generic reader function ([`read_meshio_mesh`](reference/ply3d/meshio_import.md)) that reads virtually any commonly used mesh format and loads it as a [`Mesh`](reference/ply3d/mesh.md)  object.
+
+```python exec="true" source="console" session="import"
+from ply3d.meshio_import import read_meshio_mesh
+
+mesh_filename = "example_data/teapot.obj"
+mesh = read_meshio_mesh(mesh_filename)
+```
+
+```python exec="true" result='python' session="import"
+print(mesh)
+```
+
+```python exec="true" session="import" html="true"
+from io import StringIO
+
+import pyvista as pv
+import matplotlib.pyplot as plt
+
+from ply3d.vtk_export import unstructured_grid_from_mesh
+
+grid = unstructured_grid_from_mesh(mesh)
+
+plotter = pv.Plotter(off_screen=True, window_size=(1500, 750))
+
+figure = plt.figure(figsize=(9, 4.5))
+ax = figure.gca()
+
+plotter.clear_actors()
+plotter.add_mesh(
+    grid, color='w'
+)
+plotter.add_mesh(
+    grid.extract_all_edges(), color='k', 
+    render_lines_as_tubes=True, line_width=2
+)
+plotter.view_xy(negative=False)
+plotter.zoom_camera(2.)
+
+ax.imshow(plotter.screenshot())
+ax.axis('off')
+
+buffer = StringIO()
+plt.savefig(buffer, format="svg")
+print(buffer.getvalue())
+```
+
+### Volumetric meshes
+
+In most mesh formats, volume elements (such as tetrahedra) are defined directly as lists of vertices. The PLY 3D format requires however volume elements to be defined by their bounding faces. When the mesh read through `meshio` contains volume elements but not their faces, those are created and appended to the `Mesh` face elements.
+
+!!! warning "XDMF time series"
+    
+    The XDMF mesh format supports time-indexed properties on the elements of a shared mesh. While supporting this format, only the data corresponding to the first time point will be stored as properties on the loaded `Mesh` object.
+
+
+The obtained `Mesh` object can then be converted to a PLY 3D file using the [I/O writer functions](io.md).

ply3d-0.1.0/docs/index.md

@@ -0,0 +1,110 @@
+# PLY 3D
+
+A Python library for manipulating PLY 3D geometries of multicellular tissues.
+
+## What is PLY 3D?
+
+The **PLY 3D** format is [a proposed extension](https://gitlab.com/morphodynamics/mesh/documentation/-/blob/master/PlyFormat.pdf?ref_type=heads) of the PLY Polygon File Format for meshes that allows to store 3D connected topological structures in a simple and efficient way. As it complies with [the specifications of the PLY format](https://paulbourke.net/dataformats/ply/) it uses the `.ply` extension. However, it introduces a number of specific syntaxes for mesh elements and properties, enabling to conveniently store 3D meshes composed of interconnected, arbitrary polyhedral cells - such as those used to represent multicellular biological tissues.
+
+```python exec="true" session="index" html="true"
+from io import StringIO
+
+import matplotlib.pyplot as plt
+import pyvista as pv
+
+from ply3d.ply_parser import read_ply_mesh
+from ply3d.vtk_export import unstructured_grid_from_mesh
+
+
+ply_filename = "example_data/CylinderCells.ply"
+mesh = read_ply_mesh(ply_filename)
+grid = unstructured_grid_from_mesh(mesh)
+
+plotter = pv.Plotter(off_screen=True, window_size=(1500, 1500))
+
+
+figure = plt.figure(figsize=(12, 6))
+axes = figure.subplots(1, 2)
+
+ax = axes[0]
+plotter.clear_actors()
+plotter.add_mesh(
+    grid.extract_cells_by_type(pv.CellType.POLYHEDRON).shrink(0.95),
+    scalars='label', cmap='glasbey', clim=(0, 255), show_scalar_bar=False
+)
+plotter.set_focus((0, 0, 0))
+plotter.set_position((0, 1, 1), reset=True)
+plotter.set_viewup((0, -1, 0))
+plotter.zoom_camera(1.2)
+
+ax.imshow(plotter.screenshot())
+ax.axis('off')
+
+ax = axes[1]
+plotter.clear_actors()
+plotter.add_mesh(grid.glyph(geom=pv.Sphere(radius=0.25), scale=False, orient=False), color='b')
+plotter.add_mesh(grid.extract_cells_by_type(pv.CellType.LINE).extract_geometry().tube(radius=0.1), color='m')
+plotter.add_mesh(
+    grid.extract_cells_by_type(pv.CellType.POLYGON).shrink(0.6), 
+    color='limegreen', opacity=1., 
+    style='wireframe', line_width=3
+)
+plotter.add_mesh(
+    grid.extract_cells_by_type(pv.CellType.POLYHEDRON).shrink(0.95),
+    # scalars='display_label', cmap='glasbey', clim=(0, 255)
+    color='w', opacity=0.25
+)
+
+plotter.set_focus((0, 0, 0))
+plotter.set_position((0, 1, 1), reset=True)
+plotter.set_viewup((0, -1, 0))
+plotter.zoom_camera(1.2)
+
+ax.imshow(plotter.screenshot())
+ax.axis('off')
+
+figure.tight_layout()
+
+buffer = StringIO()
+plt.savefig(buffer, format="svg")
+print(buffer.getvalue())
+```
+
+The `ply3d` Python library is a tool for manipulating and interacting with such structures stored as **PLY 3D** files. It provides high-level functions to perform the following tasks:
+<div class="grid cards" markdown>
+
+-   [:fontawesome-solid-folder-open: **I/O**](io.md)
+
+    Read and write meshes from / to files in the PLY 3D format
+
+-   [:fontawesome-solid-circle-nodes: **Data Structure**](mesh.md)
+
+    Inspect meshes and edit their elements and properties
+
+-   [:fontawesome-solid-eye: **Visualization**](visualization.md)
+
+    View meshes with their properties as [`pyvista`](https://pyvista.org/) (VTK) objects
+
+-   [:fontawesome-solid-file-import: **Conversion**](import.md)
+
+    Import meshes from other file formats through [`meshio`](https://pypi.org/project/meshio/)
+
+</div>
+
+## Installation
+
+`ply3d` is available on PyPI (the Python Package Index) and can be installed by running:
+
+```bash
+pip install ply3d
+```
+
+The library can also be installed [from sources](https://gitlab.com/morphodynamics/mesh/ply3d_python) after downloading it, by navigating to the project directory (potentially activating a virtual environment) and running: 
+
+```bash
+pip install -e .
+```
+
+!!! info "See also"
+    
+    A [C++ header-only parser for the PLY 3D format](https://gitlab.com/morphodynamics/mesh/ply3d) is also available; if this better suits your project's needs, please consider using it!

ply3d-0.1.0/docs/io.md

@@ -0,0 +1,50 @@
+# PLY 3D I/O
+
+The primary goal of the `ply3d` library is to provide a convenient way of reading PLY 3D mesh files, as well as to export geometries to that format.
+
+## Reading a PLY 3D mesh
+
+The module [`ply3d.ply_parser`](reference/ply3d/ply_parser.md) provides a parser for both ASCII and binary formatted PLY 3D files, and allows to load them as [`Mesh`](reference/ply3d/mesh.md)  objects:
+
+```python exec="true" source="console" session="io"
+from ply3d.ply_parser import read_ply_mesh
+
+ply_filename = "example_data/hexagonal_prisms.ply"
+mesh = read_ply_mesh(ply_filename)
+```
+
+```python exec="true" result='python' session="io"
+print(mesh)
+```
+
+Python offers the possibility to dynamically inspect the data represented in the `Mesh` data structure. For instance, it is straightforward to access the mesh vertex positions as a Python dictionary (where the keys correspond to the vertex indices):
+
+```python exec="true" source="console" session="io"
+mesh.vertices.points
+```
+
+```python exec="true" result='python' session="io"
+print("{")
+print(f"    0: {mesh.vertices.points[0]},")
+print(f"    1: {mesh.vertices.points[1]},")
+print("    ...")
+print(f"    {len(mesh.vertices)-2}: {mesh.vertices.points[len(mesh.vertices)-2]}")
+print(f"    {len(mesh.vertices)-1}: {mesh.vertices.points[len(mesh.vertices)-1]}")
+print("}")
+```
+
+Similarly, it is easy to access properties defined of the mesh elements as Python dictionaries. Note that these dictionaries are mutable, and that modifying them will change the data of the `Mesh`.
+
+```python exec="true" source="console" session="io"
+mesh.faces.properties['area']
+```
+
+```python exec="true" result='python' session="io"
+print("{")
+print(f"    0: {mesh.faces.properties['area'][0]},")
+print(f"    1: {mesh.faces.properties['area'][1]},")
+print("    ...")
+print(f"    {len(mesh.faces)-2}: {mesh.faces.properties['area'][len(mesh.faces)-2]}")
+print(f"    {len(mesh.faces)-1}: {mesh.faces.properties['area'][len(mesh.faces)-1]}")
+print("}")
+```

ply3d-0.1.0/docs/mesh.md

@@ -0,0 +1,104 @@
+# Mesh Data Structure
+
+Meshes in the PLY 3D format are defined by a set of **vertices**, each with a 3D position, together with collections of higher-dimension geometric elements built upon these vertices:
+
+- **edges** with their extremities defined by exactly 2 vertices
+- **faces** (polygonal) defined as an ordered list of vertices
+- **volumes** (polyhedral) delimited by an oriented set of faces
+
+## Mesh elements
+
+The structure of the central [`Mesh`](reference/ply3d/mesh.md) object in `ply3d` reflects this definition, and basically corresponds to a dictionary structure with 4 keys corresponding to the 4 mesh elements of increasing dimensions: `'vertex'`, `'edge'`, `'face'`and `'volume'`:
+
+```python exec="true" source="console" session="mesh"
+from ply3d.mesh import Mesh
+
+mesh = Mesh(
+    vertex_points=[[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]],
+    face_vertex_indices=[[0, 1, 2], [1, 3, 2]]
+)
+```
+
+```python exec="true" result='python' session="mesh"
+print(mesh)
+```
+
+These elements are accessible by their key, just as in a standard Python dictionary:
+
+```python exec="true" source="console" session="mesh"
+mesh['vertex']
+```
+
+```python exec="true" result='python' session="mesh"
+print(mesh['vertex'])
+```
+
+But convenience accessors are also provided, using the plural of the element name: 
+
+```python exec="true" source="console" session="mesh"
+mesh.faces
+```
+
+```python exec="true" result='python' session="mesh"
+print(mesh.faces)
+```
+
+## Element properties
+
+Properties can be attached to the mesh elements, as dictionaries indexed by the element **indices**, and identified by a **property name**: 
+
+```python exec="true" source="console" session="mesh"
+from numpy.random import rand, randint
+
+mesh.set_property(
+    element_name='face', property_name='random', 
+    property_dict={f: rand() for f in mesh['face'].indices}
+)
+
+mesh.set_property(
+    element_name='face', property_name='random_list', 
+    property_dict={f: [rand() for _ in range(randint(2, 5))] for f in mesh['face'].indices}
+)
+
+mesh.faces
+```
+
+```python exec="true" result='python' session="mesh"
+print(mesh.faces)
+```
+
+Properties attached to the mesh elements can be accessed just as a regular dictionary:
+
+```python exec="true" source="console" session="mesh"
+mesh.faces.properties
+```
+
+```python exec="true" result='python' session="mesh"
+print("{")
+for i_p, (property_name, property_dict) in enumerate(mesh.faces.properties.items()):
+    print(f"    '{property_name}': {{")
+    for i_v, (key, value) in enumerate(property_dict.items()):
+        print(f"        {key}: {value}{',' if i_v < len(property_dict)-1 else ''}")
+    print(f"    }}{',' if i_p < len(mesh.faces.properties)-1 else ''}")
+print("}")
+```
+
+But in addition, each property has a **type** (more precisely a list of type names) that corresponds to the way it would be typed in a PLY file header:
+
+```python exec="true" source="console" session="mesh"
+mesh.faces.properties['random'].property_type
+```
+
+```python exec="true" result='python' session="mesh"
+print(mesh.faces.properties['random'].property_type)
+```
+
+The type can be passed when setting the property on the mesh, but if none is given, it is guessed from the values of the property dictionary:
+
+```python exec="true" source="console" session="mesh"
+mesh.faces.properties['random_list'].property_type
+```
+
+```python exec="true" result='python' session="mesh"
+print(mesh.faces.properties['random_list'].property_type)
+```