{"id":51101536,"url":"https://github.com/kreshuklab/matchmaker","last_synced_at":"2026-06-24T11:01:30.560Z","repository":{"id":357601287,"uuid":"966653697","full_name":"kreshuklab/matchmaker","owner":"kreshuklab","description":"Tool for segmentation-based deformable registration ","archived":false,"fork":false,"pushed_at":"2026-06-05T12:26:01.000Z","size":7028,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-06-05T13:12:00.420Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kreshuklab.png","metadata":{"files":{"readme":"README.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-15T08:51:17.000Z","updated_at":"2026-05-24T07:24:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kreshuklab/matchmaker","commit_stats":null,"previous_names":["kreshuklab/matchmaker"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/kreshuklab/matchmaker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kreshuklab%2Fmatchmaker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kreshuklab%2Fmatchmaker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kreshuklab%2Fmatchmaker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kreshuklab%2Fmatchmaker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kreshuklab","download_url":"https://codeload.github.com/kreshuklab/matchmaker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kreshuklab%2Fmatchmaker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34728928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"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":"2026-06-24T11:01:30.007Z","updated_at":"2026-06-24T11:01:30.553Z","avatar_url":"https://github.com/kreshuklab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💞 Matchmaker\nTool for segmentation-based deformable registration and object matching\n\n## How to run\n\n### Create conda environment\n```\nconda env create -f environment.yml\n```\n\n\n### Run tests\n\nAfter activating the environment, generate the deformed test data, run the Snakemake workflow, and validate the final results with pytest:\n\n```bash\npytest -s\n```\n\nOptional: If you want to hide all warnings during tests, append:\n\n```bash\n-p no:warnings\n```\n\nThis test generates deformed test data, runs the Snakemake workflow, and compares the final outputs against pre-computed reference results.\n\nThe reference data will be downloaded automatically from this repo's release if available. If the download fails (e.g. the repository is private), manually download the reference data from [here](https://github.com/kreshuklab/matchmaker/releases/tag/test_data-v1.0) and place it under:\n\n```\nexamples/data/test_data/\n```\n\n\n### Generate rigid and elastic deformed test data\n```\npython examples/deform_test_data.py\n```\n\nThis script generates synthetic test datasets from the fixed segmentation mask stored in the repository.\n\nFirst, the original segmentation mask is rotated using a 3D rigid transformation.\n\nTwo moving datasets are then generated:\n\n- Rigid case: applies a rigid 3D rotation to the fixed volume and removes a fraction of instances.\n- Elastic case: applies a control-grid based elastic deformation, followed by a rigid rotation and instance removal.\n\nThe elastic deformation is generated from a smoothed random displacement field defined on a control grid and interpolated to full resolution.\n\nAll generated deformed volumes (`.n5` and `.tif`) are saved under:\n\n```\nexamples/data/deformed_data/\n```\n\n\n### 3 ways of interaction with the library\n\n- Running the full pipeline using workflow manager and a config file to set up registration parameters\n```\nsnakemake -s workflows/registration.smk --configfile examples/register_config_test_elastic.yaml --cores 16\n```\n- Running separate scripts\n```\nprealignment.py --fixed_path ... --fixed_key ... --moving_path ... --moving_key ... --output_dir ... --mobie_export --dataset_name ...\n```\n\n- Importing individual functions from matchmaker:\n```\nimport matchmaker as mm\n\n...\n\nmm.n5-utils.read_volume(...)\n```\n\n\n\n## Registration\n### Input\n\n- **Fixed image**: 3D instance segmentation in `n5` + resolution\n- **Moving image**: 3D instance segmentation `n5` + resolution\n\n\nExpected image shape: ZYX\n\n### Output\n- **Moving image resampled to match fixed image** `n5`\n- **QC plots**\n- **Files with all transforms**\n- **Table of correspondence between instances in moving and fixed instance segmentations**\n- **Logging file: `registration.log`**\n- **Optional: Mobie project saved at `{output_dir}/mobie_project/`**\n\n\n### Registration steps\n\n**1. PCA pre-alignment**: alignment of fixed and moving image to the PCs \\\n `prealignment.py --fixed_path ... --fixed_key ... --moving_path ... --moving_key ... --output_dir ... --mobie_export --dataset_name ...` \\\n\nOutputs:\n- prealigned images: `{file_name}_prealigned.n5`\n- transformation matrixes\n    - `{file_name}_fixed_T_prealignment.txt`\n    - `{file_name}_moving_T_prealignment.txt` (maybe final one is `moving_T_prealignment.txt`, couldn't figure this out)\n- plots:\n    - slice per dimension before pre-alignment: `{file_name}_fixed.png`, `{file_name}_moving.png`\n    - slice per dimension after pre-alignment: `{file_name}_fixed_prealigned.png`, `{file_name}_moving_prealigned.png`\n    - overlay of slice per dimension after pre-alignment: `overlay_prealignment.png`\n    - intensity profiles per axis and volume: `fixed_intensity_profile_{axis}.png`, `moving_intensity_profile_{axis}.png`\n\n**2. Rigid pre-alignment with Elastix** \\\n`apply_rigid_elastix.py --fixed_path ... --fixed_key ... --moving_path ... --moving_key ... --output_dir ... --mobie_export --dataset_name ...` \\\n\nOutputs:\n- rigid alinged moving image: `{file_name}_rigid_aligned.n5`\n- rigid transformation matrix (Elastix outputs): `result.0.mhd`, `result.0.raw`, `TransformParameters.0.txt`\n- logging file: `elastix_log_rigid.log`\n- plots:\n    - `intersample_segm_overlay_before_alignment.png`\n    - `intersample_segm_rigid_alignment_semantic.png`\n\n\n**3. Coherent point drift**\n\n**4. Matching points with mixed integer programming**\n\n**5. Deformable registration with Elastix** \\\nwith distance between keypoints in loss and rigidity penalty ---\u003e **B-spline coefficients**\n\n\n\n\n## Apply registration to other images\n### Input\n\n- **Moving image**: 3D image `n5` + resolution\n- **Files with all transforms**\n\n### Output\n- **Moving image resampled to match fixed image** - only rigid - `n5`\n- **Moving image resampled to match fixed image** - deformable - `n5`\n\nExpected image shape: (C)ZYX\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkreshuklab%2Fmatchmaker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkreshuklab%2Fmatchmaker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkreshuklab%2Fmatchmaker/lists"}