Summary

• Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

...	...	@@ -26,15 +26,77 @@
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
	33	+{{code language="bash" layout="LINENUMBERS"}}
	34	+curl -X 'POST' \
	35	+ 'https://spatial.kg.ebrains.eu/cores/ebrains/spatial_objects' \
	36	+ -H 'accept: application/json' \
	37	+ -H 'Content-Type: application/json' \
	38	+ -d '{
	39	+ "filters": "inside(hyperrectangle{[50.0,146.0,227.0], [51.0, 149.0, 228.0], \"AMB-CCF_v3-RAS\"})"
	40	+}'
	41	+{{/code}}
32	32
	43	+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.
33	33
34		-Theoretically, all data which is anchored in their respective coordinate space can be registered in the KG Spatial Search. We currently provide ingestion pipelines for data annotated with the[[ locareJSON format>>https://github.com/blixilla/LocareJSON]]. Please note that complex, planar and volumetric geometries such as polyhedrons, spheres, etc. are translated into point clouds of a configurable density during the ingestion process to ensure better performance at query time for the cost for potential false-negatives in highly fine-granular queries.
	45	+== Query by hypersphere ==
35	35
	47	+Alongside the possibility to use hyperrectangles for querying the spatial search, you can also use hyperspheres:
36	36
	49	+{{code language="javascript" layout="LINENUMBERS"}}
	50	+{
	51	+ "filters": "inside(hypersphere{[50.0,146.0,227.0], 2, \"AMB-CCF_v3-RAS\"})"
	52	+}
	53	+{{/code}}
37	37
	55	+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)
	56	+
	57	+== Advanced use: Union geometries for complex queries ==
	58	+
	59	+To build arbitrarily complex geometries, it is possible to combine hyperrectangles and hyperspheres via (nested) unions:
	60	+
	61	+{{code language="javascript" layout="LINENUMBERS"}}
	62	+{
	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\"}))"
	64	+}
	65	+{{/code}}
	66	+
	67	+== How to get the available spaces? ==
	68	+
	69	+To get a list of available spaces (to know which coordinate systems are available), please run
	70	+
	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}}
	78	+
	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	+
38	38
39	39	)))
40	40