sample usage of siibra-api to retrieve bounding boxes

[xgui3783]

Following on from the zoom meeting on 2024 08 22, one of the promises we made was a sample code on how to interact with siibra-api, in order to retrieve the bounding boxes for volumes of interest.

In this issue, we would like to outline how we would envision such a query can be done. Please feel free to comment on the issue if you have any thing unclear/any issues.

(Apologies that it took us a while to get back to this issue)

1. (Optional) Use the /spaces end point to get the IDs of interested spaces

$ curl 'https://siibra-api-prod.apps.tc.humanbrainproject.eu/v3_0/spaces?page=1&size=50' \
        | jq '.items | map({"fullName": .fullName, "@id": .["@id"] })'
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 31886  100 31886    0     0   141k      0 --:--:-- --:--:-- --:--:--  142k
[
  {
    "fullName": "BigBrain microscopic template (histology)",
    "@id": "minds/core/referencespace/v1.0.0/a1655b99-82f1-420f-a3c2-fe80fd4c8588"
  },
  {
    "fullName": "freesurfer fsaverage",
    "@id": "minds/core/referencespace/v1.0.0/tmp-fsaverage"
  },
  {
    "fullName": "freesurfer fsaverage6",
    "@id": "minds/core/referencespace/v1.0.0/tmp-fsaverage6"
  },
  {
    "fullName": "hcp32k",
    "@id": "minds/core/referencespace/v1.0.0/tmp-hcp32k"
  },
  {
    "fullName": "MNI 152 ICBM 2009c Nonlinear Asymmetric",
    "@id": "minds/core/referencespace/v1.0.0/dafcffc5-4826-4bf1-8ff6-46b8a31ff8e2"
  },
  {
    "fullName": "MEBRAINS population-based monkey template",
    "@id": "minds/core/referencespace/v1.0.0/MEBRAINS"
  },
  {
    "fullName": "MNI Colin 27",
    "@id": "minds/core/referencespace/v1.0.0/7f39f7be-445b-47c0-9791-e971c0b6d992"
  },
  {
    "fullName": "Allen Mouse Common Coordinate Framework v3",
    "@id": "minds/core/referencespace/v1.0.0/265d32a0-3d84-40a5-926f-bf89f68212b9"
  },
  {
    "fullName": "Waxholm Space of the Sprague Dawley v1.01",
    "@id": "minds/core/referencespace/v1.0.0/d5717c4a-0fa1-46e6-918c-b8003069ade8"
  }
]

From above, we are interested in

• BigBrain space (id: minds/core/referencespace/v1.0.0/a1655b99-82f1-420f-a3c2-fe80fd4c8588)
• ICBM 152 (id: minds/core/referencespace/v1.0.0/dafcffc5-4826-4bf1-8ff6-46b8a31ff8e2)

2. use the /features/Image endpoint with the relevant space ID to retrieve a list of features, including their:

• feature ID
• minpoint
• maxpoint

e.g.

$ curl 'https://siibra-api-prod.apps.tc.humanbrainproject.eu/v3_0/feature/Image?space_id=minds%2Fcore%2Freferencespace%2Fv1.0.0%2Fa1655b99-82f1-420f-a3c2-fe80fd4c8588&page=1&size=50' \
| jq '.items[:5]
	| map({
		"name": .name,
		"id": .id,
		"minpoint": .boundingbox.minpoint.coordinates | map(.value),
		"maxpoint": .boundingbox.maxpoint.coordinates | map(.value)
	})'
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  391k  100  391k    0     0  1392k      0 --:--:-- --:--:-- --:--:-- 1393k
[
  {
    "name": "Human Hippocampus scanned by Phase Contrast X-ray Tomography (XPCT)",
    "id": "7e065c31-aff6-4211-b777-dcb5050b4617--45bd80b4cce75815ff75209063881b96",
    "minpoint": [
      -27.572548,
      -4.104859425551499,
      -16.159642
    ],
    "maxpoint": [
      -17.537656613282444,
      -2.80095925,
      -9.633565140423118
    ]
  },
  {
    "name": "The Enriched Connectome - 3D polarized light imaging connectivity data of full sagittal human brain sections (HSV fibre orientation map)",
    "id": "45dcadc5e4bc290873d7790db92ce715",
    "minpoint": [
      -16.649985526032953,
      -66.19071413684445,
      -67.26197807726412
    ],
    "maxpoint": [
      -16.6,
      70.884888,
      64.064704
    ]
  },
  {
    "name": "Fiber structures of a human hippocampus based on joint DMRI, 3D-PLI, and TPFM acquisitions (HSV fibre orientation map)",
    "id": "b08a7dbc-7c75-4ce7-905b-690b2b1e8957--d3ca8fe622051466a5cde547a11111ca",
    "minpoint": [
      12.391487582038792,
      -16.951447850037418,
      -15.675784878165402
    ],
    "maxpoint": [
      38.134608,
      13.562314,
      -3.964904
    ]
  },
  {
    "name": "Fiber structures of a human hippocampus based on joint DMRI, 3D-PLI, and TPFM acquisitions (transmittance)",
    "id": "b08a7dbc-7c75-4ce7-905b-690b2b1e8957--5d19fdc3c12eff69931c82b8f3143d41",
    "minpoint": [
      11.020745,
      -2.014700305155234,
      -32.682974
    ],
    "maxpoint": [
      60.75936868788104,
      2.5332865,
      24.081565604882883
    ]
  },
  {
    "name": "WIKIBrainStem: An online atlas to manually segment the human brainstem at the mesoscopic scale from ultrahigh field MRI (T2 weighted MRI)",
    "id": "2778c2fa7c090ee0ceed1f0e5684ad57--65b6c28cb922325d1bcede37ca1354cb",
    "minpoint": [
      -13.731683,
      -62.889108,
      -44.30388
    ],
    "maxpoint": [
      24.742961896799873,
      33.554704115481705,
      -17.151722682047478
    ]
  }
]

n.b. the example above, we limited the reshaping the response to the first 5 entries
n.b. the response is paginated to 50 items max. e.g. first page page=1

$ curl 'https://siibra-api-prod.apps.tc.humanbrainproject.eu/v3_0/feature/Image?space_id=minds%2Fcore%2Freferencespace%2Fv1.0.0%2Fa1655b99-82f1-420f-a3c2-fe80fd4c8588&page=1&size=50' | jq '{"total": .total, "itemsLength": .items | length}'
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  391k  100  391k    0     0   766k      0 --:--:-- --:--:-- --:--:--  767k
{
  "total": 156,
  "itemsLength": 50
}

last page (page=4)

curl 'https://siibra-api-prod.apps.tc.humanbrainproject.eu/v3_0/feature/Image?space_id=minds%2Fcore%2Freferencespace%2Fv1.0.0%2Fa1655b99-82f1-420f-a3c2-fe80fd4c8588&page=4&size=50' | jq '{"total": .total, "itemsLength": .items | length}'
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 73851  100 73851    0     0  52002      0  0:00:01  0:00:01 --:--:-- 51971
{
  "total": 156,
  "itemsLength": 6
}