Wiki source code of kg-spatial-search

Version 12.1 by oschmid on 2023/08/22 09:31

version	line-number	content
1.1	1	(% class="jumbotron" %)
	2	(((
	3	(% class="container" %)
	4	(((
7.2	5	= KG Spatial Search =
1.1	6
7.2	7	A how-to guide to use the spatial search extension of the EBRAINS KG
1.1	8	)))
	9	)))
	10
	11	(% class="row" %)
	12	(((
	13	(% class="col-xs-12 col-sm-8" %)
	14	(((
7.2	15	= What is KG Spatial Search? =
1.1	16
7.2	17	The Spatial Search extension is an additional index which allows to search for registered datasets in the KG by spatial search - meaning that it is possible to find datasets based on their locality in the 3-dimensional space by geometries.
1.1	18
7.2	19	= Why is there an additional API to the KG Query API? =
1.1	20
7.2	21	Although in a first version, it was attempted to directly integrate the spatial search query capabilities into the KG Query API, this approach has turned out to not be ideal. The reasons for this is the increased complexity introduced into the Query API for a very specific use-case covering the needs for a small subset of the standard users who query the KG. This is why it was decided to provide the functionality as an extension instead allowing to query the ids of the datasets through the spatial search and subsequently ask the KG for the semantic meta information.
	22
	23	= What data is registered in the spatial search? =
	24
7.3	25	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. Please also note that currently only datasets can be registered for which the spatial location information is regarded to be non-sensitive from a GDPR perspective.
7.2	26
	27	= How do I query the KG Spatial Search? =
	28
7.3	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:
7.2	30
10.1	31	== Get started: Query by a "bounding box" (hyperrectangle) ==
7.3	32
8.1	33	{{code language="bash" layout="LINENUMBERS"}}
7.4	34	curl -X 'POST' \
	35	'https://spatial.kg.ebrains.eu/spatial-search/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}}
7.3	42
7.4	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.
7.2	44
10.1	45	== Query by hypersphere ==
7.2	46
7.4	47	Alongside the possibility to use hyperrectangles for querying the spatial search, you can also use hyperspheres:
	48
8.1	49	{{code language="javascript" layout="LINENUMBERS"}}
7.4	50	{
	51	"filters": "inside(hypersphere{[50.0,146.0,227.0], 2, \"AMB-CCF_v3-RAS\"})"
	52	}
	53	{{/code}}
	54
	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
10.1	57	== Advanced use: Union geometries for complex queries ==
7.4	58
	59	To build arbitrarily complex geometries, it is possible to combine hyperrectangles and hyperspheres via (nested) unions:
	60
8.1	61	{{code language="javascript" layout="LINENUMBERS"}}
7.4	62	{
8.1	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\"}))"
7.4	64	}
	65	{{/code}}
	66
	67
12.1	68	= Technical details of the ingestion pipeline =
7.4	69
12.1	70	The current pipeline is regularly parsing locareJSON files registered in the KG and translates complex geometries via the [[vtk>>https://pypi.org/project/vtk/]] library into a point cloud of a density of 1 coordinate unit (by ray-casting on an obb-tree) and uploads the resulting files to the [[bucket of this collab>>https://wiki.ebrains.eu/bin/view/Collabs/kg-spatial-search/Bucket]]. A cron job on the spatial search server pulls the files from the repo and rebuilds the databases index.
7.4	71
12.1	72
7.2	73
1.1	74	)))
	75
	76
	77	(% class="col-xs-12 col-sm-4" %)
	78	(((
	79	{{box title="Contents"}}
	80	{{toc/}}
	81	{{/box}}
	82
	83
	84	)))
	85	)))