Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions code-samples/geoscience-objects/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ The publishing notebooks use the lower-level `evo-schemas` interfaces. Use them
- [Publish a Regular 2D Grid](publish-regular-2d-grid/publish-regular-2d-grid.ipynb)
- [Publish a Triangular Mesh](publish-triangular-mesh/publish-triangular-mesh.ipynb)

## Bonus

- [Merge Triangle Meshes](bonus/merge-triangle-meshes/merge-triangle-meshes.ipynb)

## Requirements

Each notebook directory contains its own dependency instructions. You need a [supported Python version](../README.md#before-you-start), a Seequent account with Evo access, and Evo application credentials to authenticate in the notebooks.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Merge Triangle Meshes
This folder contains a Jupyter notebook showing how to select any number of existing triangle mesh objects from an Evo workspace, merge them into a single mesh, and publish the result either as a new triangle mesh object or as a new version of an existing triangle mesh object.

## Inputs
Two or more [triangle mesh](https://developer.seequent.com/docs/data-structures/geoscience-objects/schemas/objects/triangle-mesh/) objects in the selected Evo workspace. The notebook lists every triangle mesh in the workspace and you tick the ones to merge.

All selected meshes must use the same coordinate reference system, as the notebook does not reproject data. A mesh with an unspecified coordinate reference system cannot be merged with a mesh that has one.

## Outputs
- A new triangle mesh object with the name and path you provide, containing the vertices and triangles of all selected meshes. The triangle indices of each mesh are offset by the total number of vertices in the meshes before it.
- Alternatively, tick **Update existing merged mesh** and select a target mesh to publish the merge as a new version of that mesh. The target keeps its ID, name, and path. Meshes ticked for merging cannot be chosen as the target.

Only the mesh geometry is merged. Attributes, parts, and edges of the source meshes are not carried over.
Original file line number Diff line number Diff line change
@@ -0,0 +1,362 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Merge Triangle Mesh objects\n",
"\n",
"This example shows how to select any number of existing triangle mesh objects from an Evo workspace, merge them into a single mesh, and publish the result using the Evo Python SDK, either as a new triangle mesh object or as a new version of an existing triangle mesh object.\n",
"\n",
"A [triangle mesh](https://developer.seequent.com/docs/data-structures/geoscience-objects/schemas/objects/triangle-mesh/) stores its geometry in two tables:\n",
"- `triangles.vertices`: the `x`, `y`, `z` coordinates of every vertex.\n",
"- `triangles.indices`: triplets of 0-based indices (`n0`, `n1`, `n2`) into the vertex table, one row per triangle.\n",
"\n",
"To merge the meshes, their vertex tables are concatenated, and the triangle indices of each mesh are offset by the total number of vertices in the meshes before it so that they still point at the correct vertices.\n",
"\n",
"### Requirements\n",
"\n",
"You must have a Seequent account with the Evo entitlement to use this notebook.\n",
"\n",
"The following parameters must be provided:\n",
"\n",
"- The client ID of your Evo application.\n",
"- The callback/redirect URL of your Evo application.\n",
"\n",
"To obtain these app credentials, refer to the [Apps and tokens guide](https://developer.seequent.com/docs/guides/getting-started/apps-and-tokens) in the Seequent Developer Portal.\n",
"\n",
"The selected workspace must contain at least two triangle mesh objects. You can publish one using the [Publish a Triangular Mesh](../../publish-triangular-mesh/publish-triangular-mesh.ipynb) notebook."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from evo.notebooks import ServiceManagerWidget\n",
"\n",
"# Evo app credentials\n",
"client_id = \"<your-client-id>\" # Replace with your client ID\n",
"redirect_url = \"<your-redirect-url>\" # Replace with your redirect URL\n",
"\n",
"manager = await ServiceManagerWidget.with_auth_code(client_id=client_id, redirect_url=redirect_url).login()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Use the Evo Python SDK to create an object client and a data client\n",
"\n",
"The data client uses its own cache under the temp directory for Parquet files."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import os\n",
"import tempfile\n",
"\n",
"from evo.common.utils import Cache\n",
"from evo.objects import ObjectAPIClient\n",
"\n",
"# The object client will manage your auth token and Geoscience Object API requests.\n",
"object_client = ObjectAPIClient(manager.get_environment(), manager.get_connector())\n",
"\n",
"parquet_cache = Cache(os.path.join(tempfile.gettempdir(), \"evo-notebook-data\"), mkdir=True)\n",
"print(f\"Caching Parquet data in: {parquet_cache.root}\")\n",
"\n",
"# The data client will manage downloading and saving your data as Parquet and publishing your data to Evo storage.\n",
"data_client = object_client.get_data_client(parquet_cache)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Create the triangle mesh helper\n",
"\n",
"[triangle_mesh_helpers.py](triangle_mesh_helpers.py) contains the helpers used in this notebook:\n",
"- `TriangleMeshHelper` lists the triangle meshes in the workspace, downloads mesh data, preserves the coordinate reference system, and displays a link to view the new object in the Evo portal.\n",
"- `MeshSelectorWidget` displays a checkbox for each mesh, plus fields for the name and path of the merged mesh. Alternatively, tick **Update existing merged mesh** to pick an existing mesh to update instead."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from triangle_mesh_helpers import TriangleMeshHelper\n",
"\n",
"mesh_helper = TriangleMeshHelper(object_client, data_client)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Select the triangle meshes to merge\n",
"\n",
"List all triangle mesh objects in the workspace and tick the checkboxes of the meshes to merge (at least two). Use **Select all** to toggle every mesh at once. You can also set the name and path of the merged object that will be published.\n",
"\n",
"To publish the merge as a new version of an existing mesh instead of creating a new object, tick **Update existing merged mesh** and select the target mesh from the dropdown. The target keeps its ID, name and path, and its geometry is replaced by the merge of the selected meshes. The dropdown only lists meshes that are not ticked for merging, and is updated as you change the selection."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from triangle_mesh_helpers import MeshSelectorWidget\n",
"\n",
"triangle_mesh_objects = await mesh_helper.list_triangle_meshes()\n",
"if len(triangle_mesh_objects) < 2:\n",
" raise RuntimeError(\n",
" f\"Found {len(triangle_mesh_objects)} triangle mesh object(s) in the workspace, but at least two are required. \"\n",
" )\n",
"\n",
"print(f\"Found {len(triangle_mesh_objects)} triangle mesh objects.\")\n",
"mesh_selector = MeshSelectorWidget(triangle_mesh_objects)\n",
"mesh_selector"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Download and merge the selected meshes\n",
"\n",
"Run the cell below after making your selections. All selected meshes must use the same coordinate reference system; this is checked before any mesh data is downloaded. The vertices of all selected meshes are concatenated and the triangle indices of each mesh are offset by the total number of vertices in the meshes before it.\n",
"\n",
"> **Note:** Only the mesh geometry is merged. Attributes, parts and edges of the source meshes are not carried over to the merged mesh."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import numpy as np\n",
"\n",
"selected_meshes = mesh_selector.selected_meshes\n",
"if len(selected_meshes) < 2:\n",
" raise ValueError(f\"Select at least two triangle meshes to merge ({len(selected_meshes)} selected).\")\n",
"if mesh_selector.update_existing and mesh_selector.target_mesh is None:\n",
" raise ValueError(\"Select the target mesh to update, or untick 'Update existing merged mesh'.\")\n",
"\n",
"# Download only the object definitions first, so the coordinate reference systems can be checked before any data is downloaded.\n",
"mesh_objects = []\n",
"meshes_by_crs = []\n",
"for mesh in selected_meshes:\n",
" mesh_object = await mesh_helper.download_triangle_mesh_object(mesh)\n",
" mesh_objects.append(mesh_object)\n",
"\n",
" crs = mesh_object.get(\"coordinate_reference_system\") or \"unspecified\"\n",
" crs_group = next((paths for group_crs, paths in meshes_by_crs if group_crs == crs), None)\n",
" if crs_group is None:\n",
" crs_group = []\n",
" meshes_by_crs.append((crs, crs_group))\n",
" crs_group.append(mesh.path)\n",
"\n",
"# All meshes must share the same coordinate reference system, and an unspecified CRS does not match a specified one.\n",
"# This notebook does not reproject data.\n",
"if len(meshes_by_crs) > 1:\n",
" crs_details = \"\\n\".join(\n",
" f\" - {mesh_helper.describe_crs(crs)}: \" + \", \".join(f\"'{path}'\" for path in paths)\n",
" for crs, paths in meshes_by_crs\n",
" )\n",
" raise ValueError(\n",
" f\"Cannot merge the selected meshes because they use {len(meshes_by_crs)} different coordinate \"\n",
" f\"reference systems:\\n{crs_details}\\n\"\n",
" \"Deselect the meshes that do not match, or reproject them to a common coordinate reference system \"\n",
" \"and run this cell again.\"\n",
" )\n",
"merged_crs = meshes_by_crs[0][0]\n",
"\n",
"vertex_arrays, index_arrays = [], []\n",
"mesh_summaries = []\n",
"vertex_offset = 0\n",
"for mesh, mesh_object in zip(selected_meshes, mesh_objects):\n",
" vertices, indices = await mesh_helper.download_triangle_mesh_data(mesh, mesh_object)\n",
"\n",
" vertex_arrays.append(vertices)\n",
" index_arrays.append(indices + np.uint64(vertex_offset))\n",
" vertex_offset += len(vertices)\n",
" mesh_summaries.append((len(vertices), len(indices), mesh.path))\n",
"\n",
"merged_vertices = np.vstack(vertex_arrays)\n",
"merged_indices = np.vstack(index_arrays)\n",
"\n",
"print(f\"{'Vertices':>12} {'Triangles':>12} Mesh\")\n",
"for vertex_count, triangle_count, mesh_path in mesh_summaries:\n",
" print(f\"{vertex_count:>12,} {triangle_count:>12,} {mesh_path}\")\n",
"print(f\"{len(merged_vertices):>12,} {len(merged_indices):>12,} Merged mesh ({len(selected_meshes)} meshes)\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Save the merged vertices and indices as Parquet\n",
"\n",
"The vertices are saved using the `float-array-3` table format and the triangle indices using the `index-array-3` table format, as required by the triangle mesh schema."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import pyarrow as pa\n",
"from evo_schemas.components import BoundingBox_V1_0_1, Triangles_V1_2_0_Indices, Triangles_V1_2_0_Vertices\n",
"\n",
"from evo.objects.utils.table_formats import FLOAT_ARRAY_3, INDEX_ARRAY_3\n",
"\n",
"vertices_table = pa.table(\n",
" {\n",
" \"x\": pa.array(merged_vertices[:, 0], type=pa.float64()),\n",
" \"y\": pa.array(merged_vertices[:, 1], type=pa.float64()),\n",
" \"z\": pa.array(merged_vertices[:, 2], type=pa.float64()),\n",
" }\n",
")\n",
"indices_table = pa.table(\n",
" {\n",
" \"n0\": pa.array(merged_indices[:, 0], type=pa.uint64()),\n",
" \"n1\": pa.array(merged_indices[:, 1], type=pa.uint64()),\n",
" \"n2\": pa.array(merged_indices[:, 2], type=pa.uint64()),\n",
" }\n",
")\n",
"\n",
"mesh_vertices = Triangles_V1_2_0_Vertices.from_dict(data_client.save_table(vertices_table, table_format=FLOAT_ARRAY_3))\n",
"mesh_indices = Triangles_V1_2_0_Indices.from_dict(data_client.save_table(indices_table, table_format=INDEX_ARRAY_3))\n",
"\n",
"# Define the bounding box from the merged vertices.\n",
"min_x, min_y, min_z = merged_vertices.min(axis=0)\n",
"max_x, max_y, max_z = merged_vertices.max(axis=0)\n",
"merged_bounding_box = BoundingBox_V1_0_1(\n",
" min_x=float(min_x),\n",
" max_x=float(max_x),\n",
" min_y=float(min_y),\n",
" max_y=float(max_y),\n",
" min_z=float(min_z),\n",
" max_z=float(max_z),\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Create the merged triangle mesh and publish it to Evo\n",
"\n",
"Geoscience object data must comply to a specific object schema. The `evo-schemas` package provides Pydantic models that make it easy to work with the equivalent JSON schemas. For this example we'll use v2.2.0 of the triangle mesh schema, via the relevant Pydantic model.\n",
"\n",
"If **Update existing merged mesh** is ticked, the object is given the UUID and name of the target mesh and published with `update_geoscience_object`, which creates a new version of the target. Otherwise, a new object is created at the name and path you entered with `create_geoscience_object`.\n",
"\n",
"> **Note:** When updating an existing mesh, the new version replaces the target's description, tags, bounding box and coordinate reference system with those of the merged mesh. Its previous versions are kept in Evo."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import os\n",
"from datetime import datetime, timezone\n",
"\n",
"from evo_schemas.components import Triangles_V1_2_0\n",
"from evo_schemas.objects import TriangleMesh_V2_2_0\n",
"\n",
"from evo.notebooks import FeedbackWidget\n",
"\n",
"target_mesh = mesh_selector.target_mesh if mesh_selector.update_existing else None\n",
Comment thread
shivangj-10 marked this conversation as resolved.
Resolved
"\n",
"if target_mesh is None:\n",
" object_name = mesh_selector.merged_name.strip() or \"Merged_Mesh_SDK_demo\"\n",
" if object_name.endswith(\".json\"):\n",
" object_name = object_name[: -len(\".json\")]\n",
" if os.environ.get(\"CI\"):\n",
" object_name += f\"_{datetime.now(timezone.utc).strftime('%Y%m%d_%H%M%S_%f')}\"\n",
" object_path = mesh_selector.merged_path.strip().strip(\"/\")\n",
"\n",
" # The object name requires the `.json` extension.\n",
" full_obj_path = f\"{object_path}/{object_name}.json\" if object_path else f\"{object_name}.json\"\n",
"else:\n",
" # Keep the name of the target mesh; its ID and path do not change when a new version is published.\n",
" object_name = target_mesh.name[: -len(\".json\")] if target_mesh.name.endswith(\".json\") else target_mesh.name\n",
Comment thread
shivangj-10 marked this conversation as resolved.
Resolved
" full_obj_path = target_mesh.path\n",
"\n",
"merged_mesh = TriangleMesh_V2_2_0(\n",
" name=object_name,\n",
" uuid=None if target_mesh is None else target_mesh.id,\n",
" description=f\"Merge of {len(selected_meshes)} triangle meshes: \"\n",
" + \", \".join(f\"'{mesh.path}'\" for mesh in selected_meshes)\n",
" + \".\",\n",
" bounding_box=merged_bounding_box,\n",
" tags={\"Source\": \"Jupyter Notebook\"},\n",
" coordinate_reference_system=mesh_helper.to_crs_model(merged_crs),\n",
" triangles=Triangles_V1_2_0(vertices=mesh_vertices, indices=mesh_indices),\n",
")\n",
"\n",
"# Upload the Parquet data to Evo.\n",
"await data_client.upload_referenced_data(merged_mesh.as_dict(), FeedbackWidget(\"Uploading data\"))\n",
"\n",
"if target_mesh is None:\n",
" # Create a new geoscience object.\n",
" merged_mesh_metadata = await object_client.create_geoscience_object(full_obj_path, merged_mesh.as_dict())\n",
" print(f\"Published merged triangle mesh to '{full_obj_path}' (Object ID: {merged_mesh_metadata.id})\")\n",
"else:\n",
" # Publish a new version of the target geoscience object.\n",
" merged_mesh_metadata = await object_client.update_geoscience_object(merged_mesh.as_dict())\n",
" print(\n",
" f\"Published a new version of '{full_obj_path}' (Object ID: {merged_mesh_metadata.id}, \"\n",
" f\"Version ID: {merged_mesh_metadata.version_id})\"\n",
" )"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### View the object in the Evo portal"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"mesh_helper.build_portal_url(merged_mesh_metadata)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Success! You now have a geoscience object in Evo containing the merged mesh data, either as a new object or as a new version of the target mesh.\n",
"\n",
"## Summary\n",
"\n",
"In this example, we've completed the following:\n",
"* Listed the triangle mesh objects in a workspace and selected the meshes to merge using checkboxes.\n",
"* Downloaded the vertex and triangle index data of each selected mesh.\n",
"* Merged the meshes by concatenating the vertices and offsetting the triangle indices of each mesh by the number of preceding vertices.\n",
"* Saved the merged data in Parquet format and combined it into the triangle-mesh schema format.\n",
"* Uploaded the Parquet files and the assembled object in JSON format to Evo, either as a new object or as a new version of an existing mesh."
]
}
],
"metadata": {},
"nbformat": 4,
"nbformat_minor": 4
}
Loading
Loading