Changes for page kg-spatial-search

Last modified by oschmid on 2023/08/22 11:23
From version 7.4
edited by oschmid
on 2023/08/22 09:22
Change comment: There is no comment for this version
To version 16.1
edited by oschmid
on 2023/08/22 11:23
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -26,14 +26,13 @@
26 26  
27 27  = How do I query the KG Spatial Search? =
28 28  
29 -Simply use the API endpoint at [[https:~~/~~/spatial.kg.ebrains.eu/api/>>https://spatial.kg.ebrains.eu/api/]] by running queries according to the following examples:
29 +Simply use the API endpoint at [[https:~~/~~/spatial.kg.ebrains.eu/cores/ebrains/spatial_objects>>https://spatial.kg.ebrains.eu/spatial_objects]] by running queries according to the following examples:
30 30  
31 +== Get started: Query by a "bounding box" (hyperrectangle) ==
31 31  
32 -==== Get started: Query by a "bounding box" (hyperrectangle) ====
33 -
34 -{{code}}
33 +{{code language="bash" layout="LINENUMBERS"}}
35 35  curl -X 'POST' \
36 - 'https://spatial.kg.ebrains.eu/spatial-search/cores/ebrains/spatial_objects' \
35 + 'https://spatial.kg.ebrains.eu/cores/ebrains/spatial_objects' \
37 37   -H 'accept: application/json' \
38 38   -H 'Content-Type: application/json' \
39 39   -d '{
... ... @@ -43,12 +43,11 @@
43 43  
44 44  As you can see, you're sending a POST request to the endpoint at **https:~/~/spatial.kg.ebrains.eu/spatial-search/cores/ebrains/spatial_objects  **with a payload defining a geometry of interest. In this case, we're looking for all objects that are **inside **a **hyperrectangle **defined by its lowest and highest point in the coordinate system of the coordinate space **AMB-CCF_v3-RAS**. This query will return you an array of ids of the objects located within the geometry which you then can use to conveniently query the KG either through the [[Instance API>>https://core.kg.ebrains.eu/swagger-ui/index.html#/2%20Advanced/getInstancesByIds]] or the [[Query API>>https://core.kg.ebrains.eu/swagger-ui/index.html#/1%20Basic/runDynamicQuery]] to access detailed meta information.
45 45  
45 +== Query by hypersphere ==
46 46  
47 -==== Query by hypersphere ====
48 -
49 49  Alongside the possibility to use hyperrectangles for querying the spatial search, you can also use hyperspheres:
50 50  
51 -{{code}}
49 +{{code language="javascript" layout="LINENUMBERS"}}
52 52  {
53 53   "filters": "inside(hypersphere{[50.0,146.0,227.0], 2, \"AMB-CCF_v3-RAS\"})"
54 54  }
... ... @@ -56,28 +56,49 @@
56 56  
57 57  It is defined by the center of the sphere with its coordinates, the radius in coordinate units and the coordinate space of the given coordinates (in this case again AMB-CCF_v3-RAS)
58 58  
57 +== Advanced use: Union geometries for complex queries ==
59 59  
60 -
61 -==== Advanced use: Union geometries for complex queries ====
62 -
63 63  To build arbitrarily complex geometries, it is possible to combine hyperrectangles and hyperspheres via (nested) unions:
64 64  
65 -{{code}}
61 +{{code language="javascript" layout="LINENUMBERS"}}
66 66  {
67 - "filters": "
68 - union(
69 - union(
70 - inside(hyperrectangle{[50.0,146.0,227.0], [51.0, 149.0, 228.0], \"AMB-CCF_v3-RAS\"}),
71 - inside(hyperrectangle{[120.0,146.0,227.0], [150.0, 180.0, 300.0], \"AMB-CCF_v3-RAS\"})
72 - ),
73 - inside(hypersphere{[50.0,146.0,227.0], 2, \"AMB-CCF_v3-RAS\"})
74 - )"
63 + "filters": "union(union(inside(hyperrectangle{[50.0,146.0,227.0], [51.0, 149.0, 228.0], \"AMB-CCF_v3-RAS\"}), inside(hyperrectangle{[120.0,146.0,227.0], [150.0, 180.0, 300.0], \"AMB-CCF_v3-RAS\"})),inside(hypersphere{[50.0,146.0,227.0], 2, \"AMB-CCF_v3-RAS\"}))"
75 75  }
76 76  {{/code}}
77 77  
67 +== How to get the available spaces? ==
78 78  
69 +To get a list of available spaces (to know which coordinate systems are available), please run
79 79  
71 +{{code language="bash" layout="LINENUMBERS"}}
72 +curl -X 'POST' \
73 + 'https://spatial.kg.ebrains.eu/spaces' \
74 + -H 'accept: application/json' \
75 + -H 'Content-Type: application/json' \
76 + -d '{}'
77 +{{/code}}
80 80  
79 +to retrieve a list of spaces. To get more information about the space, you can then ask for a specific one with
80 +
81 +{{code language="bash" layout="LINENUMBERS"}}
82 +curl -X 'GET' \
83 + 'https://spatial.kg.ebrains.eu/spaces/AMB-CCF_v3-RAS' \
84 + -H 'accept: application/json' \
85 + -H 'Content-Type: application/json'
86 +{{/code}}
87 +
88 +
89 += Technical details of the ingestion pipeline =
90 +
91 +The current pipeline is regularly parsing locareJSON files registered in the KG.
92 +
93 +* Points are translated to the data structure of spatial search without manipulation
94 +* Polyhedrons are translated via the [[vtk>>https://pypi.org/project/vtk/]] library into a point cloud of (currently) a density of 1 coordinate unit (by ray-casting on an obb-tree)
95 +* Other geometries are work-in-progress
96 +
97 +The resulting files (all representing point-clouds) as well as the space definitions are uploaded to the [[bucket of this collab>>https://data-proxy.ebrains.eu/kg-spatial-search]]. A cron job running on the spatial search server pulls the files from the repo and rebuilds the databases index in regular intervals.
98 +
99 +
81 81  
82 82  )))
83 83