{"id":15065045,"url":"https://github.com/andreasmazur/geoconv","last_synced_at":"2025-07-26T22:09:40.505Z","repository":{"id":51565646,"uuid":"478050290","full_name":"andreasMazur/geoconv","owner":"andreasMazur","description":"A Python library for end-to-end learning on surfaces. It implements pre-processing functions that include geodesic algorithms, neural network layers that operate on surfaces, visualization tools and benchmarking functionalities.","archived":false,"fork":false,"pushed_at":"2025-04-10T08:04:38.000Z","size":9175,"stargazers_count":33,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-10T09:27:28.584Z","etag":null,"topics":["benchmarking","convolutional-neural-networks","deep-learning","deep-neural-networks","geodesic-algorithm","geometric-deep-learning","geometry-processing","keras","machine-learning","neural-network","neural-networks","tensorflow","visualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andreasMazur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-05T09:03:17.000Z","updated_at":"2025-03-23T12:20:20.000Z","dependencies_parsed_at":"2023-10-04T17:26:09.912Z","dependency_job_id":"df91e869-199d-4564-8419-2fad26108867","html_url":"https://github.com/andreasMazur/geoconv","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreasMazur%2Fgeoconv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreasMazur%2Fgeoconv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreasMazur%2Fgeoconv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreasMazur%2Fgeoconv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andreasMazur","download_url":"https://codeload.github.com/andreasMazur/geoconv/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248224759,"owners_count":21068074,"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","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":["benchmarking","convolutional-neural-networks","deep-learning","deep-neural-networks","geodesic-algorithm","geometric-deep-learning","geometry-processing","keras","machine-learning","neural-network","neural-networks","tensorflow","visualization"],"created_at":"2024-09-25T00:30:02.218Z","updated_at":"2025-04-10T13:09:26.085Z","avatar_url":"https://github.com/andreasMazur.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GeoConv\n\n## Let's bend planes to curved surfaces.\n\n\u003cimg align=\"right\" style=\"margin-left: 10px; width: 180px;\" src=\"geoconv_cartoon.png\"\u003e\n\nIntrinsic mesh CNNs [1] operate directly on object surfaces, therefore expanding the application of convolutions to\nnon-Euclidean data.\n\n**GeoConv** is a library that provides end-to-end tools for deep learning on surfaces.\nThat is, whether it is pre-processing your mesh files into a format that can be fed into neural networks, or the\nimplementation of the **intrinsic surface convolutions** [1] themselves, GeoConv has you covered.\n\n## Implementation\n\nWhile this library is theoretically motivated by the work of [1], [2] and [3] it also adds additional functionalities\nsuch as the freedom of specifying new kernels, preprocessing algorithms like the one from [4], as well as visualization \nand benchmark tools to verify your layer configuration, your pre-processing results or your trained models.\n\nGeoConv provides the base layer `ConvIntrinsic` as a Tensorflow or Pytorch layer. Both implementations are equivalent.\nOnly the ways in how they are configured slightly differ due to differences regarding Tensorflow and Pytorch. Check the\nminimal example below or the `geoconv_examples`-package for how you configure Intrinsic Mesh CNNs.\n\n## Installation\n1. Install **[BLAS](https://netlib.org/blas/#_reference_blas_version_3_10_0)** and **[CBLAS](https://netlib.org/blas/#_cblas)**:\n    ```bash\n    sudo apt install libatlas-base-dev\n    ```\n\n2. Install **geoconv**:\n    \n    | Installation Variant                 | Command                                                                                 |\n    |--------------------------------------|-----------------------------------------------------------------------------------------|\n    | GeoConv                              | `pip install geoconv`                                                                   |\n    | GeoConv + Tensorflow/Keras (**CPU**) | `pip install geoconv[tensorflow]`                                                       |\n    | GeoConv + Tensorflow/Keras (**GPU**) | `pip install geoconv[tensorflow_gpu]`                                                   |\n    | GeoConv + Pytorch (**CPU**)          | `pip install geoconv[pytorch] --extra-index-url https://download.pytorch.org/whl/cpu`   |\n    | GeoConv + Pytorch (**GPU**)          | `pip install geoconv[pytorch] --extra-index-url https://download.pytorch.org/whl/cu118` |\n\n3. If you want to run the FAUST example you also need to install:\n    ```bash\n    sudo apt install libflann-dev libeigen3-dev lz4\n    pip install cython==0.29.37\n    pip install pyshot@git+https://github.com/uhlmanngroup/pyshot@master\n    ```\n\n4. In case OpenGL context cannot be created:\n    ```bash\n    conda install -c conda-forge libstdcxx-ng\n    ```\n\n### Minimal Example (TensorFlow)\n\n```python\nfrom geoconv.tensorflow.layers.conv_geodesic import ConvGeodesic\nfrom geoconv.tensorflow.layers.angular_max_pooling import AngularMaxPooling\n\nimport keras\n\n\ndef define_model(input_dim, output_dim, n_radial, n_angular):\n     \"\"\"Define a geodesic convolutional neural network\"\"\"\n\n     signal_input = keras.layers.InputLayer(shape=(input_dim,))\n     barycentric = keras.layers.InputLayer(shape=(n_radial, n_angular, 3, 2))\n     signal = ConvGeodesic(\n          amt_templates=32,  # 32-dimensional output\n          template_radius=0.03,  # maximal geodesic template distance \n          activation=\"relu\",\n          rotation_delta=1  # Delta in between template rotations\n     )([signal_input, barycentric])\n     signal = AngularMaxPooling()(signal)\n     logits = keras.layers.Dense(output_dim)(signal)\n\n     model = keras.Model(inputs=[signal_input, barycentric], outputs=[logits])\n     return model\n```\n\n### Minimal Example (PyTorch)\n\n```python\nfrom geoconv.pytorch.layers.conv_geodesic import ConvGeodesic\nfrom geoconv.pytorch.layers.angular_max_pooling import AngularMaxPooling\n\nfrom torch import nn\n\n\nclass GCNN(nn.Module):\n     def __init__(self, input_dim, output_dim, n_radial, n_angular):\n          super().__init__()\n          self.geodesic_conv = ConvGeodesic(\n               input_shape=[(None, input_dim), (None, n_radial, n_angular, 3, 2)],\n               amt_templates=32,  # 32-dimensional output\n               template_radius=0.03,  # maximal geodesic template distance \n               activation=\"relu\",\n               rotation_delta=1  # Delta in between template rotations\n          )\n          self.amp = AngularMaxPooling()\n          self.output = nn.Linear(in_features=32, out_features=output_dim)\n\n     def forward(self, x):\n          signal, barycentric = x\n          signal = self.geodesic_conv([signal, barycentric])\n          signal = self.amp(signal)\n          return self.output(signal)\n```\n\n### Inputs and preprocessing\n\nAs visible in the minimal examples above, the intrinsic surface convolutional layer (here geodesic convolution) expects\ntwo inputs:\n1. The signal defined on the mesh vertices (can be anything from descriptors like SHOT [5] to simple 3D-coordinates of\nthe vertices).\n2. Barycentric coordinates for signal interpolation in the format specified by the output of\n``compute_barycentric_coordinates``.\n\nFor the latter: **GeoConv** supplies you with the necessary preprocessing functions:\n1. Use ``GPCSystemGroup(mesh).compute(u_max=u_max)`` on your triangle meshes (which are stored in a format that is\nsupported by **[Trimesh](https://trimsh.org/index.html)**, e.g. 'ply') to compute local geodesic polar coordinate systems with the algorithm\nof [4].\n2. Use those GPC-systems and ``compute_barycentric_coordinates`` to compute the barycentric coordinates for the kernel \nvertices. The result can without further effort directly be fed into the layer.\n\n**For more thorough explanations on how GeoConv operates check out the `geoconv_examples`-package!**\n\n## Cite\n\nUsing my work? Please cite this repository by using the **\"Cite this repository\"-option** of GitHub\nin the right panel.\n\n## Referenced Literature\n\n[1]: Bronstein, Michael M., et al. \"Geometric deep learning: Grids, groups, graphs, geodesics, and gauges.\" \n     arXiv preprint arXiv:2104.13478 (2021).\n\n[2]: Monti, Federico, et al. \"Geometric deep learning on graphs and manifolds using mixture model cnns.\" Proceedings\n     of the IEEE conference on computer vision and pattern recognition. 2017.\n\n[3]: Poulenard, Adrien, and Maks Ovsjanikov. \"Multi-directional geodesic neural networks via equivariant convolution.\"\n     ACM Transactions on Graphics (TOG) 37.6 (2018): 1-14.\n\n\n[4]: Melvær, Eivind Lyche, and Martin Reimers. \"Geodesic polar coordinates on polygonal meshes.\" Computer Graphics \n     Forum. Vol. 31. No. 8. Oxford, UK: Blackwell Publishing Ltd, 2012.\n\n[5]: Tombari, Federico, Samuele Salti, and Luigi Di Stefano. \"Unique signatures of histograms for local surface\n     description.\" European conference on computer vision. Springer, Berlin, Heidelberg, 2010.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreasmazur%2Fgeoconv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandreasmazur%2Fgeoconv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreasmazur%2Fgeoconv/lists"}