Skip to content

Notebooks examples #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 30 commits into from
Jun 16, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
dddf16d
Added proposal for sync
MarcelGeo May 27, 2025
9dbc582
added push an dpull using client.
MarcelGeo May 27, 2025
cb8807a
add user management example
fernandinand May 27, 2025
103e36c
Fix users creation from CSV section
fernandinand May 30, 2025
f892757
Add scenario for projects management
fernandinand May 30, 2025
9a4b8bf
Fix project version/status entry.
fernandinand May 30, 2025
3781d4c
some tnning and cleanup for 1. and 3. scenario
MarcelGeo Jun 9, 2025
cf73378
small tweaks
MarcelGeo Jun 9, 2025
a1c12e6
make images smaller
MarcelGeo Jun 9, 2025
b39e6bb
AB tteams tweaks
MarcelGeo Jun 9, 2025
90d582d
Add README with some basic info
fernandinand Jun 11, 2025
07218d5
Merge remote-tracking branch 'origin/master' into notebooks-examples
MarcelGeo Jun 12, 2025
df732ce
Update examples/02_sync.ipynb
MarcelGeo Jun 16, 2025
8ab9a87
Update examples/02_sync.ipynb
MarcelGeo Jun 16, 2025
180cc6a
Update examples/03_projects.ipynb
MarcelGeo Jun 16, 2025
efde843
Update examples/03_projects.ipynb
MarcelGeo Jun 16, 2025
7fd7581
Update examples/README.md
MarcelGeo Jun 16, 2025
c8258f3
Update examples/03_projects.ipynb
MarcelGeo Jun 16, 2025
7133736
Update examples/03_projects.ipynb
MarcelGeo Jun 16, 2025
7f8396c
Update examples/03_projects.ipynb
MarcelGeo Jun 16, 2025
5c0f5a9
Update examples/03_projects.ipynb
MarcelGeo Jun 16, 2025
3929c1b
Update examples/03_projects.ipynb
MarcelGeo Jun 16, 2025
c0378f4
Update examples/02_sync.ipynb
MarcelGeo Jun 16, 2025
ccedfe6
Update examples/02_sync.ipynb
MarcelGeo Jun 16, 2025
7056aed
Update examples/02_sync.ipynb
MarcelGeo Jun 16, 2025
0b3e6ce
Update examples/02_sync.ipynb
MarcelGeo Jun 16, 2025
9499c1f
Update examples/02_sync.ipynb
MarcelGeo Jun 16, 2025
96ee0a6
Update examples/02_sync.ipynb
MarcelGeo Jun 16, 2025
c566a27
Update examples/02_sync.ipynb
MarcelGeo Jun 16, 2025
55b743a
Update examples/02_sync.ipynb
MarcelGeo Jun 16, 2025
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
502 changes: 502 additions & 0 deletions examples/01_users.ipynb

Large diffs are not rendered by default.

6 changes: 6 additions & 0 deletions examples/01_users_assets/users.csv
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
username,email
jdoe,[email protected]
asmith,[email protected]
bwilliams,[email protected]
cjohnson,[email protected]
omartin,[email protected]
265 changes: 265 additions & 0 deletions examples/02_sync.ipynb
Original file line number Diff line number Diff line change
@@ -0,0 +1,265 @@
{
"cells": [
{
"cell_type": "markdown",
"id": "eff75b76",
"metadata": {},
"source": [
"# Mergin Maps Synchronisation\n",
"\n",
"Mergin Maps synchronisation operates using a push/pull mechanism for your project. \n",
"\n",
"- **Push**: Synchronise your local project changes to the Mergin Maps server\n",
"- **Pull**: Updates from the server are synchronised to the local device\n",
"\n",
"## Example project\n",
"\n",
"Imagine you are preparing a project for tree surveyors in Vienna.\n",
"\n",
"The task for the surveyors is to collect data about existing trees in the city. They are focusing on the health of the trees. In this example, we will use the Mergin Maps Python API client to automatically synchronise data to the Mergin Maps server. We will import CSV data into a GeoPackage and synchronize it. This GeoPackage can then be used for further data collection in the field."
]
},
{
"cell_type": "markdown",
"id": "8eb25fff",
"metadata": {},
"source": [
"Let's install Mergin Maps client and necessary libraries for this example."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "33ac4583",
"metadata": {},
"outputs": [],
"source": [
"!pip install mergin-client"
]
},
{
"cell_type": "markdown",
"id": "611a93c1",
"metadata": {},
"source": [
"Fill the following variables with your Mergin Maps credentials (username / email and password)."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1bd4f48d",
"metadata": {},
"outputs": [],
"source": [
"LOGIN=\"...\"\n",
"PASSWORD=\"...\""
]
},
{
"cell_type": "markdown",
"id": "8a68900f",
"metadata": {},
"source": [
"Let's login to your account to be able to use the `MerginClient` class methods to automate your workflows."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c332f11f",
"metadata": {},
"outputs": [],
"source": [
"import mergin\n",
"\n",
"client = mergin.MerginClient(\n",
" login=LOGIN,\n",
" password=PASSWORD\n",
")"
]
},
{
"cell_type": "markdown",
"id": "3b3b55cd",
"metadata": {},
"source": [
"Now you can use the client to call the API. Let's try to clone the project available for this example (`lutraconsulting/Vienna trees example`) to your Mergin Maps project. You need to specify to which project our sample project will be cloned to (edit the `PROJECT` variable in the form `{WORKSPACE NAME}/{PROJECT NAME}` in Mergin Maps cloud)."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "70f17d60",
"metadata": {},
"outputs": [],
"source": [
"PROJECT=\".../...\"\n",
"\n",
"client.clone_project(\"lutraconsulting/Vienna trees example\", PROJECT)"
]
},
{
"cell_type": "markdown",
"id": "ff9dd71b",
"metadata": {},
"source": [
"Project contains GeoPackage `Ready to survey trees` where surveyors can collect trees health and `vienna_trees_gansehauffel.csv` file with all trees from Gänsehäufel in Vienna. Let's download project to your computer using `download_project` method. "
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "08fc0642",
"metadata": {},
"outputs": [],
"source": [
"# download project to local folder.\n",
"LOCAL_FOLDER=\"/tmp/project\"\n",
"\n",
"client.download_project(PROJECT, LOCAL_FOLDER)"
]
},
{
"cell_type": "markdown",
"id": "400194dc",
"metadata": {},
"source": [
"We can now add sample points from the `.csv` file to the GeoPackage. These points within the GeoPackage will then be available to surveyors in the field for editing the health column using the Mergin Maps mobile app."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "23469139",
"metadata": {},
"outputs": [],
"source": [
"# Install geopandas to export csv to geopackage\n",
"!pip install geopandas"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f3002ce3",
"metadata": {},
"outputs": [],
"source": [
"import pandas as pd\n",
"import geopandas as gpd\n",
"import os\n",
"\n",
"# Get the data from the CSV (use just sample of data)\n",
"csv_file = os.path.join(LOCAL_FOLDER, \"vienna_trees_gansehauffel.csv\")\n",
"csv_df = pd.read_csv(csv_file, nrows=20, dtype={\"health\": str})\n",
"# Convert geometry in WKT format to GeoDataFrame\n",
"gdf = gpd.GeoDataFrame(csv_df, geometry=gpd.GeoSeries.from_wkt(csv_df.geometry))\n",
"print(gdf.head())\n",
"# Save the GeoDataFrame to a Geopackage\n",
"gdf.to_file(\n",
" os.path.join(LOCAL_FOLDER, \"Ready_to_survey_trees.gpkg\"), \n",
" layer=\"Ready_to_survey_trees\", driver=\"GPKG\",\n",
")\n"
]
},
{
"cell_type": "markdown",
"id": "d440ee5d",
"metadata": {},
"source": [
"You can now see changes in GeoPackage file using `project_status` method. "
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "d1a67839",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[{'path': 'Ready_to_survey_trees.gpkg', 'checksum': '3ba7658d231fefe30d9410f41c75f37d1ba5e614', 'size': 98304, 'mtime': datetime.datetime(2025, 5, 27, 16, 24, 30, 122463, tzinfo=tzlocal()), 'origin_checksum': '19b3331abc515a955691401918804d8bcf397ee4', 'chunks': ['be489067-d078-4862-bae1-c1cb222f680a']}]\n"
]
}
],
"source": [
"_, push_changes, __ = client.project_status(LOCAL_FOLDER)\n",
"print(push_changes.get(\"updated\"))"
]
},
{
"cell_type": "markdown",
"id": "506cfa68",
"metadata": {},
"source": [
"You can now use `push_project` method to push data to the server."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1a167b17",
"metadata": {},
"outputs": [],
"source": [
"client.push_project(LOCAL_FOLDER)"
]
},
{
"cell_type": "markdown",
"id": "caccc6da",
"metadata": {},
"source": [
"To pull the latest version of the project, use `pull_project` method."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "90e5e64a",
"metadata": {},
"outputs": [],
"source": [
"client.pull_project(LOCAL_FOLDER)"
]
},
{
"cell_type": "markdown",
"id": "e65bb7c9",
"metadata": {},
"source": [
"Mobile app users are now enabled to perform updates to the imported tree data directly in the field.\n",
"\n",
"<img src=\"./02_sync_assets/synchronized_trees.jpg\" alt=\"drawing\" width=\"250\"/>\n",
"\n",
"Editing tree health with predefined values.\n",
"\n",
"<img src=\"./02_sync_assets/edit_tree_health.jpg\" alt=\"drawing\" width=\"250\"/>"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "python-api-client",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.14"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
Binary file added examples/02_sync_assets/edit_tree_health.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added examples/02_sync_assets/synchronized_trees.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading