{"id":22632006,"url":"https://github.com/alleninstitute/stpt_registration","last_synced_at":"2025-10-29T07:49:26.398Z","repository":{"id":145221317,"uuid":"239768678","full_name":"AllenInstitute/stpt_registration","owner":"AllenInstitute","description":"STPT registration methods","archived":false,"fork":false,"pushed_at":"2020-02-14T05:10:13.000Z","size":179,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-09-09T04:25:02.258Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AllenInstitute.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2020-02-11T13:29:22.000Z","updated_at":"2025-01-07T01:47:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"4c496c41-16aa-4d41-9bb2-68f5fa0746aa","html_url":"https://github.com/AllenInstitute/stpt_registration","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AllenInstitute/stpt_registration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenInstitute%2Fstpt_registration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenInstitute%2Fstpt_registration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenInstitute%2Fstpt_registration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenInstitute%2Fstpt_registration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AllenInstitute","download_url":"https://codeload.github.com/AllenInstitute/stpt_registration/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenInstitute%2Fstpt_registration/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281584986,"owners_count":26526171,"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-29T02:00:06.901Z","response_time":59,"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":[],"created_at":"2024-12-09T02:14:51.502Z","updated_at":"2025-10-29T07:49:26.392Z","avatar_url":"https://github.com/AllenInstitute.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Overview\n\nThis repository contains code for methods to register serial two-photon tomography (STPT) images\nfrom the Allen Mouse Connectivity Atlas as described in \n[Oh et. al., 2014](https://www.ncbi.nlm.nih.gov/pubmed/24695228/) and\n[Kuan et. al., 2015](https://www.ncbi.nlm.nih.gov/pubmed/25536338/).\nThese methods were also used in the construction of the average template of the \n[Allen Mouse Common Coordinate Framework](https://community.brain-map.org/t/allen-mouse-ccf-accessing-and-using-related-data-and-tools/359).\n\n# STPT Registration Methods\n\nThe three main executables are:\n\n## idpProjectionAlignmentModule\nThis module performs a \"global\" registration between the STPT images and a target reference.\nThe module first performs a rigid registration followed by an affine (12 parameters) registration. In both cases using \nmutual information as the similarity metric and employing a multi-resolution optimization strategy. Input to this module is an xml file\ncontaining meta-data for the image-series including the location, size and resolution of each image file. \nThe output of this module is a \"transform\" xml.\nFor each image, it contains the 2D transform to reconstruct the specimen. For STPT, this is simply the identity transform since\nthe data is already inherently 3D. \nFor the image series, it contains the 3D transform that will align the STPT specimen to the target reference.\n\nSource: [lims2_modules/common/register/Registration/idpProjectionAlignmentModule.cxx](lims2_modules/common/register/Registration/idpProjectionAlignmentModule.cxx)\n\n\n## idpProjectionLocalAlignmentModule\nFollowing the \"global\" registration step, this module performs a \"local\" deformable registration\nto improve the fine scale alignment of the STPT images to the target reference. \nIn this method, deformation was parameterized as 3D B-splines (order of 3) where the knots are placed on a regularly spaced grid.\nA four level coarse-to-fine optimization strategy was used. \nA coarse grid implicitly only allows smooth/stiff deformations while a finer grid allows more elastic transformations.\nThe method starts with a coarse grid allowing large scale anatomy to be matched.\nThe result is then used to initialize the finer levels allowing local neighborhoods to be more accurately matched. \n\nAt each level, cross-correlation is used as the similarity metric. To speed up computation,\nthe metric was only evaluated on a small portion of randomly selected voxels.\nThe optimization problem was formulated and solved as a graph labeling problem. \nSpecifically, instead of considering all the possible continuous moves of each knot, \nthe search space is discretized into a number of grids represented by labels. \nThe registration was performed in both the forward and backward direction in each iteration and then composed to form the final transform, \nresulting in a symmetric and invertible deformation field. \n\nInput to this module are two xml files, the first containing image-series metadata and the second contains the affine transforms \ncomputed during the \"global\" registration step. The output of this module is the final B-spline grid and associated deformation field.\n\nSource: [lims2_modules/common/register/Registration/idpProjectionLocalAlignmentModule.cxx](lims2_modules/common/register/Registration/idpProjectionLocalAlignmentModule.cxx)\n\n\n## idpProjectionResampleVolumeRGBModule\nFollowing the \"local\" deformable registration step, this module enables the warping\nof the STPT images to create an output volume that is aligned to the target reference. Input to this module\nare the image-series meta-data and transform xml files as well as the deformation field computed during \"local\" deformable registration.\n\nSource: [lims2_modules/common/register/Registration/idpProjectionResampleVolumeRGBModule.cxx](lims2_modules/common/register/Registration/idpProjectionResampleVolumeRGBModule.cxx)\n\n# The \"model_directory\"\n\nReference data and algorithm parameters needed by the registration methods are organized in a directory structure.\nIn the production pipeline, the modules access this directory at a standard default location. Each module has an optional \"model_directory\" input argument to configure the modules to look for that information in user specified location. \n\nA copy of the content of the \"model_directory\" used for registering STPT images is located [here](http://download.alleninstitute.org/publications/allen_mouse_brain_common_coordinate_framework/).\n\n\n# Level of Support\n\nThese methods were implemented as part of an informatics data processing pipeline and as such the \ndesign is influenced by the need to communicate with the internal database, workflow and build management\nsystems and to operate efficiently with internal file formats (eg JPEG2000) and compute cluster. A high level of technical\nexpertise may be required to compile the code and all its dependent packages, \nformat image files into the required format and the generation and parsing of highly structured and verbose input/output xml files.\n\nWe have not deployed these methods beyond the scope of our own STPT images and computing cluster.\n\nWe are not currently supporting this code, but simply releasing it to the community AS IS. We are not able to provide any guarantees of support. The community is welcome to submit issues, but you should not expect an active response.\n\n# Dependencies\n\nThese methods leverage several libraries. While many are open source, some require specific licensing agreements.\nPlease see the documentation for each library for further details.\n\n* **ITK** https://itk.org/, Version: InsightToolkit-3.20.0\n\n* **VTK** https://vtk.org/, Version: VTK-5.10.0\n\n* **Kakadu** https://kakadusoftware.com/, Version: v6_4_1-00465M\n\n* **Boost** https://www.boost.org/, Version: boost_1_54_0\n\n* **TinyXML** http://www.grinninglizard.com/tinyxml/, Version: tinyxml.2.6.2\n\n* **CMake** https://cmake.org/, Version: cmake-2.8\n\n\n# Build Instructions\n\n* Download each dependency and build according to the instructions for each package\n* Update the following files with the location of each dependency\n  - [lims2_modules/lib/ITKJP2Lib/build/configure.sh](lims2_modules/lib/ITKJP2Lib/build/configure.sh)\n  - [lims2_modules/common/register/build/configure.sh](lims2_modules/common/register/build/configure.sh)\n* Change directory to [lims2_modules/common/register/](lims2_modules/common/register/)\n* Run command [build/build_projection.sh](lims2_modules/common/register/build/build_projection.sh)\n\n\n# Example Runtimes\n\n* Example global alignment job\n  - Limits:\tmem=6gb,vmem=6gb,walltime=05:00:00,neednodes=centos\n  - Resources: cput=00:05:49,vmem=1265748kb,walltime=00:06:04,mem=1731724kb\n  - Node: x86_64, Linux, 3.10.0-514.26.2.el7.x86_64, 32 CPUs, 3000 MHz\n\n* Example local alignment job including image resampling\n  - Limits: mem=20gb,vmem=20gb,walltime=05:00:00,neednodes=centos\n  - Resources: cput=00:45:11,vmem=17240312kb,walltime=00:45:42,mem=14007624kb\n  - Node: x86_64, Linux, 3.10.0-514.26.2.el7.x86_64, 24 CPUs, 2500 MHz\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleninstitute%2Fstpt_registration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falleninstitute%2Fstpt_registration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleninstitute%2Fstpt_registration/lists"}