Skip to content

Commit 767b059

Browse files
aurelienlombardAurelien Lombard
aurelienlombard
and
Aurelien Lombard
authored
chore(LAB-2768): add documentation for multi-layer geosat import (#1673)
Co-authored-by: Aurelien Lombard <[email protected]>
1 parent 7d5d85a commit 767b059

File tree

6 files changed

+424
-4
lines changed

6 files changed

+424
-4
lines changed

‎docs/sdk/tutorials/importing_multilayer_geosat_assets.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
<!-- FILE AUTO GENERATED BY docs/utils.py DO NOT EDIT DIRECTLY -->
2+
<a href="https://colab.research.google.com/github/kili-technology/kili-python-sdk/blob/main/recipes/importing_multilayer_geosat_assets.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>
3+
4+
# How to import multi-layer geosat assets to a Kili project
5+
6+
In this tutorial, we will learn how to import multi-layer geosat assets to your project.
7+
8+
Here are the steps that we will follow:
9+
10+
1. Setting up an image project.
11+
2. Importing some multi-layer assets to Kili with GEOTIFFs and layers from a public tile server.
12+
13+
## Setting up a Kili image project to work with
14+
15+
### Installing and instantiating Kili
16+
17+
First, let's install and import the required modules.
18+
19+
20+
```python
21+
%pip install kili
22+
```
23+
24+
25+
```python
26+
from kili.client import Kili
27+
```
28+
29+
Now, let's set up variables needed to create an instance of the Kili object.
30+
31+
We will need your API key and Kili's API endpoint.
32+
33+
If you are unsure how to look up your API key, refer to [https://docs.kili-technology.com/docs/creating-an-api-key](https://docs.kili-technology.com/docs/creating-an-api-key).
34+
35+
36+
```python
37+
api_key = "YOUR_API_KEY"
38+
api_endpoint = "https://cloud.kili-technology.com/api/label/v2/graphql"
39+
kili = Kili(api_endpoint=api_endpoint, api_key=api_key, verify=True)
40+
```
41+
42+
### Creating an image Kili project
43+
44+
To create an IMAGE Kili project, you must first set up its ontology.
45+
46+
Here, we will only add a classification task:
47+
48+
49+
```python
50+
interface = {
51+
"jobs": {
52+
"OBJECT_DETECTION_JOB": {
53+
"content": {
54+
"categories": {
55+
"PLANE": {
56+
"children": [],
57+
"color": "#472CED",
58+
"name": "Plane",
59+
"id": "category3",
60+
}
61+
},
62+
"input": "radio",
63+
},
64+
"instruction": "BBOX",
65+
"mlTask": "OBJECT_DETECTION",
66+
"required": 0,
67+
"tools": ["rectangle"],
68+
"isChild": False,
69+
"isNew": False,
70+
}
71+
}
72+
}
73+
74+
project = kili.create_project(
75+
title="[Kili SDK Notebook]: Importing multi-layer Geosatellite asset",
76+
description="Project Description",
77+
input_type="IMAGE",
78+
json_interface=interface,
79+
)
80+
```
81+
82+
## Importing your assets
83+
84+
### Download geotiff file examples
85+
86+
Before adding assets you need to download our geotiff examples and add them in a geosat folder, created in the same folder as where you run your python script. It is mandatory to use local files and not urls for geosatellite files.
87+
88+
89+
```python
90+
import os
91+
import urllib.request
92+
93+
if not os.path.exists("geosat"):
94+
os.makedirs("geosat")
95+
urllib.request.urlretrieve(
96+
"https://storage.googleapis.com/label-public-staging/asset-test-sample/geosat/a.tiff",
97+
"geosat/a.tiff",
98+
)
99+
urllib.request.urlretrieve(
100+
"https://storage.googleapis.com/label-public-staging/asset-test-sample/geosat/b.tiff",
101+
"geosat/b.tiff",
102+
)
103+
```
104+
105+
### Add Multi-Layer assets to your project
106+
107+
You can now add assets. Here is an example to add 2 geotiffs and a public layer coming from the openstreetmap tile server.
108+
109+
110+
```python
111+
project_id = project["id"]
112+
json_metadata_array = [{"processingParameters": {"epsg": 3857}}]
113+
multi_layer_content_array = [
114+
[
115+
{
116+
"path": "geosat/a.tiff",
117+
"name": "Layer 1",
118+
"isBaseLayer": False,
119+
},
120+
{
121+
"path": "geosat/b.tiff",
122+
"name": "Layer 2",
123+
"isBaseLayer": False,
124+
},
125+
],
126+
]
127+
json_content_array = [
128+
[
129+
{
130+
"name": "osm",
131+
"tileLayerUrl": "https://b.tile.openstreetmap.org/{z}/{x}/{y}.png",
132+
"epsg": "EPSG3857",
133+
"bounds": [
134+
[11.17010498046875, 44.308941579503745],
135+
[13.67478942871094, 46.542667432984864],
136+
],
137+
"useClassicCoordinates": False,
138+
"minZoom": 10,
139+
"maxZoom": 18,
140+
"isBaseLayer": True,
141+
}
142+
]
143+
]
144+
145+
kili.append_many_to_dataset(
146+
project_id=project_id,
147+
multi_layer_content_array=multi_layer_content_array,
148+
json_metadata_array=json_metadata_array,
149+
json_content_array=json_content_array,
150+
)
151+
```
152+
153+
In this example 4 arguments are used for the `append_many_to_dataset` function :
154+
155+
1. `project_id`: the id of the project to which you want to add the asset
156+
1. `multi_layer_content_array`: it is a list of dictionnaries representing the layers created from geosatellite files like GEOTIFFS. For each GEOTIFF you have to set the `path` to the GEOTIFF, the `name` that will be used in kili for the layer and the boolean `isBaseLayer` to define if it's a base layer (only one visible at a time) or an overlay layer (a layer that will be displayed on top of the base layer). This last one is optional and by default if no parameter is set, we consider it is a base layer.
157+
1. `json_metadata_array`: This one contains the processing parameters that will be used when processing the files. 3 parameters can be set there :
158+
1. `epsg`: This one defines the projection (<https://en.wikipedia.org/wiki/EPSG_Geodetic_Parameter_Dataset>) to which we will reproject the dataset. Our frontend supports only two projections : `EPSG:4326` and `EPSG:3857`. If this parameter is not set we will keep the projection of the initial file if it is one of these two, else we will reproject it by default to `EPSG:3857`. By default, we advise to not set this parameter but if you need to use your GEOTIFFS with some tile server (as with openstreetmap here) you will need to reproject it to the same EPSG as the one used by the tile server as our application supports only one EPSG for the whole asset. For your information most of the well known tile server (openstreetmap, googlemaps, etc) are using `EPSG:3857`.
159+
1. `maxZoom` and `minZoom`: these defines limits of zoom for your GEOTIFF files. This is especially useful for files that will be tiled by our server (file size > 30MB). By default we generate all the zooms until the one of the original file but if you want to limit to specific zoom levels you can constrain them with these parameters.
160+
1. `json_content_array`: It has to be used when you need to add public tile layers to your asset. You can find the same arguments as for GEOTIFF layers `name`, `minZoom`, `maxZoom`, `isBaseLayer`. You also need to specify the `epsg` but with the format `EPSG{number}` (this one correspond to the EPSG used by the tile server, we will not reproject anything). And then, you have to provide the url to the tile server with the parameter `tileLayerUrl` and the `bounds`, corresponding to the minimum and maximum latitude and longitude for which you want to request tiles (use the following format `[[min_lng, min_lat],[max_lng, max_lat]]`). Finally, the `useClassicCoordinates: False` has always to be provided to explain that geospatial coordinates are used.
161+
162+
## Cleanup
163+
164+
We can remove the project that we created if needed:
165+
166+
167+
```python
168+
kili.delete_project(project_id)
169+
```

‎docs/tutorials.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Because videos and Rich Text assets may be more complex to import, we’ve creat
1919
- For video assets, refer to [this tutorial](https://python-sdk-docs.kili-technology.com/latest/sdk/tutorials/importing_video_assets/).
2020
- For rich text assets, see [here](https://python-sdk-docs.kili-technology.com/latest/sdk/tutorials/import_text_assets).
2121
- For PDF assets, see [here](https://python-sdk-docs.kili-technology.com/latest/sdk/tutorials/importing_pdf_assets).
22+
- For Geosat multi-layer assets, see [here](https://python-sdk-docs.kili-technology.com/latest/sdk/tutorials/importing_multilayer_geosat_assets).
2223

2324
## Importing labels
2425

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ nav:
3939
- Video Assets: sdk/tutorials/importing_video_assets.md
4040
- PDF Assets: sdk/tutorials/importing_pdf_assets.md
4141
- Rich Text Assets: sdk/tutorials/import_text_assets.md
42+
- Multi-Layer Geosatellite Assets: sdk/tutorials/importing_multilayer_geosat_assets.md
4243
- Importing Labels:
4344
- Importing Labels: sdk/tutorials/importing_labels.md
4445
- OpenAI NER Pre-annotations: sdk/tutorials/ner_pre_annotations_openai.md

0 commit comments

Comments
 (0)