{"id":24562578,"url":"https://github.com/humanbrainproject/hbp-spatial-backend","last_synced_at":"2026-03-02T19:02:56.544Z","repository":{"id":46684226,"uuid":"175443438","full_name":"HumanBrainProject/hbp-spatial-backend","owner":"HumanBrainProject","description":"An HTTP backend for transforming coordinates and data between the core template spaces of the HBP","archived":false,"fork":false,"pushed_at":"2025-08-14T12:02:47.000Z","size":474,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-08-14T14:09:29.633Z","etag":null,"topics":["neuroimaging"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HumanBrainProject.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-03-13T15:01:10.000Z","updated_at":"2025-04-01T15:18:52.000Z","dependencies_parsed_at":"2024-03-15T17:41:33.409Z","dependency_job_id":"9a83fb37-e591-47bc-b558-a1f2ef93ee34","html_url":"https://github.com/HumanBrainProject/hbp-spatial-backend","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HumanBrainProject/hbp-spatial-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanBrainProject%2Fhbp-spatial-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanBrainProject%2Fhbp-spatial-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanBrainProject%2Fhbp-spatial-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanBrainProject%2Fhbp-spatial-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HumanBrainProject","download_url":"https://codeload.github.com/HumanBrainProject/hbp-spatial-backend/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanBrainProject%2Fhbp-spatial-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278321378,"owners_count":25967866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["neuroimaging"],"created_at":"2025-01-23T09:16:27.256Z","updated_at":"2025-10-04T13:30:33.076Z","avatar_url":"https://github.com/HumanBrainProject.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"An HTTP backend for transforming coordinates (and, in the future, data) between the HBP core template spaces\n\n.. image:: https://github.com/HumanBrainProject/hbp-spatial-backend/actions/workflows/tox.yaml/badge.svg\n   :target: https://github.com/HumanBrainProject/hbp-spatial-backend/actions/workflows/tox.yaml\n   :alt: Build Status\n\n.. image:: https://codecov.io/gh/HumanBrainProject/hbp-spatial-backend/branch/master/graph/badge.svg\n   :target: https://codecov.io/gh/HumanBrainProject/hbp-spatial-backend\n   :alt: Coverage Status\n\n.. image:: https://img.shields.io/swagger/valid/3.0?label=OpenAPI\u0026specUrl=https%3A%2F%2Fhbp-spatial-backend.apps.hbp.eu%2Fopenapi.json\n   :target: https://hbp-spatial-backend.apps.hbp.eu/redoc\n   :alt: Swagger Validator\n\n\nPublic deployments\n==================\n\nA production deployment (following the ``master`` branch) is deployed on https://hbp-spatial-backend.apps.hbp.eu. |uptime-prod|\n\nA docker image is pushed to `docker-registry.ebrains.eu/hbp-spatial-backend/server:latest \u003chttps://docker-registry.ebrains.eu/harbor/projects/112/repositories/server\u003e`_\n\nThe public deployments are managed by helm and kubernetes, the relevant configuration is described in `\u003c.helm/\u003e`_.\n\n\nDocumentation\n=============\n\nThe API is documented using the OpenAPI standard (a.k.a. Swagger): see `the ReDoc-generated documentation \u003chttps://hbp-spatial-backend.apps.hbp.eu/redoc\u003e`_.\n\n`A Swagger UI page \u003chttps://hbp-spatial-backend.apps.hbp.eu/swagger-ui\u003e`_ is also available for trying out the API.\n\nStep-by-step tutorial on docker example\n=======================================\n\nPre-requisites\n--------------\n\nDocker needs to be installed.\n\nIf we don't want to use sudo for docker, we use the following commands:\n\n.. code-block:: shell\n\n   # Commands to use docker as non-sudo user\n   sudo groupadd docker\n   sudo usermod -aG docker $USER\n\n\nAt this stage, we can either login/logout or reboot the machine and check if docker is working:\n\n.. code-block:: shell\n\n   # To check that it works. It should output no error:\n   docker ps\n\nFirst steps\n-----------\n\nFirst, we build the docker image:\n\n.. code-block:: shell\n\n   # Command to run from the directory hbp-spatial-backend\n   # This creates the container hbp-spatial-backend\n   docker build -t hbp-spatial-backend .\n\nThen, we mount data directory (where our nifti files lie)\ninto the directory /Data of the container and we run the docker container:\n\n.. code-block:: shell\n\n   # Runs the container and mounts your data directory\n   # containing your nii files into the container directory /Data\n   # Change DATA_DIR to match your local data directory\n   DATA_DIR=/your/path/to/data/dir\n   docker run -t -i --rm -p 8080:8080 -v $DATA_DIR:/Data hbp-spatial-backend\n\nThis has launched the flask server and has opened a bash shell in the container.\n\nTo check that it works, we now make a simple request from inside the container:\n\n.. code-block:: shell\n\n   # From inside the container\n   curl -X GET \"http://localhost:8080/v1/graph.yaml\" -H  \"accept: */*\"\n\nThis reads the transformation graphs stored in the container.\nThe end of the output should be similar to this:\n\n.. image:: image/output_graph_yaml.png\n\nTo check that AIMS tools have been installed properly,\nwe now launch from inside the container the AimsApplyTransform help command:\n\n.. code-block:: shell\n\n   AimsApplyTransform --help\n\n\nWe can also have access to the server from outside the container:\n\n.. code-block:: shell\n\n   # From outside the container, use the IP of your docker container\n   # (to know it, run ifconfig)\n   DOCKER_IP=172.17.0.1\n   curl -X GET \"http://$DOCKER_IP:8080/v1/graph.yaml\" -H  \"accept: */*\"\n\nNote that you can also recover the same information directly from the web API:\n\n.. code-block:: shell\n\n   curl -X GET \"https://hbp-spatial-backend.apps.hbp.eu/v1/graph.yaml\" -H  \"accept: */*\"\n\nNow, it is time to get our first transformation:\n\nGetting our first local transformation\n--------------------------------------\n\nFor this part, we will make use of the following dataset:\nhttps://doi.org/10.25493/KJQN-AM0\nThis is the whole-brain parcellation of the Julich-Brain Cytoarchitectonic Atlas (v2.6).\nThe parcellation is done in the MNI ICBM 152 2009c nonlinear asymmetric reference space.\nIn this paragraph, we will transform this parcellation\ndone in the MNI ICBM 152 reference space into the Big Brain reference space.\n\n\nOn the web page https://doi.org/10.25493/KJQN-AM0,\nwe click on \"download dataset\" and on \"download all related data as zip\".\n\nWe now copy the nifti file that we will use\ninto the data directory (DATA_DIR used above):\n\n.. code-block:: shell\n\n   # From the host\n   mkdir -p $DATA_DIR/tutorial_hbp_spatial_backend\n   mv JulichBrain_MPMAtlas_l_N10_nlin2Stdicbm152asym2009c_publicDOI_3f5ec6016bc2242769c41befdbc1b2e0.nii.gz $DATA_DIR/tutorial_hbp_spatial_backend/julich-brain-l-native-mni152.nii.gz\n   mv JulichBrain_MPMAtlas_l_N10_nlin2Stdicbm152asym2009c_publicDOI_3f5ec6016bc2242769c41befdbc1b2e0.xml $DATA_DIR/tutorial_hbp_spatial_backend/julich-brain-l-native-mni152.xml\n\nNow, the nifti file julich-brain-l-native-mni152.nii.gz is accessible from the docker container at the location /Data/tutorial_hbp_spatial_backend.\n\nWe can visualize it (for example using Anatomist; note that the visualisation steps are not described here)\ntogether with the MNI152 template:\n\n.. image:: image/julich-brain-l-native-mni152.png\n   :width: 50%\n\n\nThere are utilities (get_local_image_transform_command.py)\nto get the transform command from the server, format it and launch the AimsApplyTransform.\nThese utilities are contained in the container at the location /root/get_local_image_transform_command.py:\n\n.. code-block:: shell\n\n   # From the docker container\n   cd /root\n   ./get_local_image_transform_command.py --help\n\nWe now give to the program:\n* the server address,\n* the reference space of the input file (\"MNI 152 ICBM 2009c Nonlinear Asymmetric\"),\n* the desired reference space of the output file (\"Big Brain (Histology)\"),\n* the path of the input file (/Data/tutorial_hbp_spatial_backend/julich-brain-l-native-mni152.nii.gz),\n* the path of the output file (here, /Data/tutorial_hbp_spatial_backend/julich-brain-l-in-bigbrain.nii.gz).\n\n.. code-block:: shell\n\n   # From the docker container\n   ./get_local_image_transform_command.py -a http://localhost:8080 -s \"MNI 152 ICBM 2009c Nonlinear Asymmetric\" -t \"Big Brain (Histology)\" -i /Data/tutorial_hbp_spatial_backend/julich-brain-l-native-mni152.nii.gz -o /Data/tutorial_hbp_spatial_backend/julich-brain-l-in-bigbrain.nii.gz --interp nearest\n\nAfter around one minute, the transformed file is created. The python script has made a request to the server to get the transform command and has launched AimsApplyTransform with the  correct transformations.\n\nNote here that we have used an extra option (--interp nearest). It is an option that has been passed further to AimsApplyTransform.\nIt is only necessary because the file used is a file of labels (namely, the labels of the parcellation), thus the default linear interpolation is not correct. But, in the usual case, we will not add this option.\n\nWe now represent the left-brain parcellation together with the big brain template (using Anatomist):\n\n.. image:: image/julich-brain-l-in-bigbrain.png\n   :width: 50%\n\nGetting transformations to other reference spaces\n-------------------------------------------------\n\nWe can use now the same script to get the parcellation into the MNI Colin 27\nreference space. For this, we will change only the target space (-t \"MNI Colin 27\") and the output file.\n\nBelow, we visualize the parcellation transformed into the MNI Colin 27 space:\n\n.. image:: image/julich-brain-l-in-colin27.png\n   :width: 50%\n\nWe can also use it to get the parcellation into the infant reference space.\nAgain, we will change only the target space (-t \"Infant Atlas\") and the output file.\n\nBelow, we visualize the parcellation in the infant reference space:\n\n.. image:: image/julich-brain-l-in-infant.png\n   :width: 50%\n\n\nDevelopment\n===========\n\nThe backend needs to call ``AimsApplyTransform``, which is part of `the AIMS image processing toolkit \u003chttps://github.com/brainvisa/aims-free\u003e`_. You can use `\u003cdocker-aims/script.sh\u003e`_ to build a Docker image containing these tools (a pre-built image is available on Docker Hub: `jchavas/brainvisa-aims \u003chttps://hub.docker.com/r/jchavas/brainvisa-aims\u003e`_).\n\nUseful commands for development:\n\n.. code-block:: shell\n\n  git clone https://github.com/HumanBrainProject/hbp-spatial-backend.git\n\n  # Install in a virtual environment\n  cd hbp-spatial-backend\n  python3 -m venv venv/\n  . venv/bin/activate\n  pip3 install -e .[dev]\n\n  export FLASK_APP=hbp_spatial_backend\n  flask run  # run a local development server\n\n  # Tests\n  pytest  # run tests\n  pytest --cov=hbp_spatial_backend --cov-report=html  # detailed test coverage report\n  tox  # run tests under all supported Python versions\n\n  # Please install pre-commit if you intend to contribute\n  pip install pre-commit\n  pre-commit install  # install the pre-commit hook\n\n  # Before a commit, you can launch the pre-commit:\n  pre-commit run --all-files\n\nContributing\n============\n\nThis repository uses `pre-commit`_ to ensure that all committed code follows minimal quality standards. Please install it and configure it to run as a pre-commit hook in your local repository (see above).\n\n\n.. |uptime-prod| image:: https://img.shields.io/uptimerobot/ratio/7/m783468831-04ba4c898048519b8c7b5a2f?style=flat-square\n   :alt: Weekly uptime ratio of the production instance\n.. _pre-commit: https://pre-commit.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumanbrainproject%2Fhbp-spatial-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhumanbrainproject%2Fhbp-spatial-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumanbrainproject%2Fhbp-spatial-backend/lists"}