{"id":22702909,"url":"https://github.com/kbevers/transformo","last_synced_at":"2025-06-14T21:03:11.851Z","repository":{"id":266067848,"uuid":"539343479","full_name":"kbevers/Transformo","owner":"kbevers","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-13T10:19:51.000Z","size":173,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-14T21:01:55.076Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kbevers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2022-09-21T06:41:12.000Z","updated_at":"2025-06-13T10:16:53.000Z","dependencies_parsed_at":"2025-02-02T22:24:11.761Z","dependency_job_id":"2dc86eff-427d-4f85-aa4b-8a63f1f24ba5","html_url":"https://github.com/kbevers/Transformo","commit_stats":null,"previous_names":["kbevers/transformo"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kbevers/Transformo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbevers%2FTransformo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbevers%2FTransformo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbevers%2FTransformo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbevers%2FTransformo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kbevers","download_url":"https://codeload.github.com/kbevers/Transformo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbevers%2FTransformo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259884416,"owners_count":22926440,"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","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-10T07:15:52.544Z","updated_at":"2025-06-14T21:03:11.836Z","avatar_url":"https://github.com/kbevers.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Transformo\n\nTransformo is a generalized software package for estimating geodetic transformation\nparameters and models.\n\nTransformo seeks to provide a framework that lets the user focus on determining the\nbest transformation model. To achieve that, the burden of reading coordinate data\nfrom various sources, (re)implementing algorimths and delivering the results in\na useful an accessable form has been removed.\n\nThe main problem Transformo tries to solve can be presented on the idealized form\n\n```\nT = M(p, S)\n```\n\nWhere `S` and `T` are the source and target coordinates, `M` is a transformation\nmodel and `p` is the parameters for the chosen model.\n\nThe real world is rarely simple so a more realistic form would be\n\n```\nT = M(p, S) + R\n```\n\nWhere `R` is the transformation residuals.\n\nThe primary function of Transformo is to provide a set of parameters `p` that\nminimizesthe residual `R`. In some cases that might involve a transformation model\nconsisting of several steps:\n\n```\nT = M3(p3, M2(p2, M1(p1, S))) + R\n```\n\nWith transformo we can easily specify the `S`, `T` and `M1`, `M2`, and `M3` using\nthe built-in constructs, which leaves only the parameters, `p1`, `p2` and `p3`, to\nbe determined. Transformo will do that based on the specified model and present\nthe results in a suitable format.\n\n## Rationale\n\nThe rationale behind Transformo is to create a framework that removes the tedious\nwork of reading input data and presenting the results after transformation\nparameters has been determined. In particular, this approch is meant to be a service\nto researchers that develop new for methods geodetic coordinate transformations, as\nthey can focus on the core algorithms and not the supporting scaffolding.\n\n## Installation\n\nTransformo is best run in a Conda environment. Clone the repository from GitHub\nand run the following commands in the root:\n\n```sh\nmamba env create -f environment.yml\nmamba activate transformo\npip install .\n```\n\n## Using Transformo\n\nTransformo is a command line application that expects a YAML-file as input.\nThe YAML-file defines a pipeline of datasources, operators and presenters.\nOnce the pipeline has been processed by Transformo the results can be displayed\nin the terminal or saved to a file in various formats.\n\nHere's an example:\n\n```sh\ntransformo pipeline.yaml --pdf pipeline.yaml\n```\n\nwhich will produce a PDF-file with the results of the processed pipeline.\n\nThe file `pipeline.yaml` might look something like:\n\n```yaml\nsource_data:\n- name: ITRF2014\n  type: csv\n  filename: test/data/dk_cors_itrf2014.csv\ntarget_data:\n- name: ETRS89\n  type: csv\n  filename: test/data/dk_cors_etrs89.csv\noperators:\n- type: helmert_translation\npresenters:\n- name: PROJ string\n  type: proj_presenter\n- name: Coordinates\n  type: coordinate_presenter\n```\n\nNote that some pipeline entries are named and some aren't. The name attribute\nis optional but are useful when working with bigger pipelines. For named\npresenters the name will used as section headers for the presenter output in the\nreport.\n\nIn the `examples/` directory a number of example pipelines are available, that\ncan be used as inspiration for creating your own. Run them from the root of the\nTransformo repository:\n\n```sh\ntransformo --report-in-terminal examples/bells_and_whistles.yaml\n```\n\n## Use cases\n\n* Estimate a 7-parameter Helmert transformation\n* Derive the next iteration of the NKG Transformations\n* Adjust a geoid model to a height system\n* ...\n\n## Architecture\n\nThe overall architecture consists of a pipeline on the form\n\n```\nDATASOURCE_1                                                        PRESENTER_1\n\nDATASOURCE_2                                                        PRESENTER_2\n\nDATASOURCE_3   -\u003e OPERATOR_1 -\u003e OPERATOR_2 -\u003e ... \u003e OPERATOR_N -\u003e   PRESENTER_3\n\n    ...                                                              ...\n\nDATASOURCE_N                                                        PRESENTER_N\n```\n\nwhere *datasources* gathers sets of source and target coordinates and velocities and\nassembles them in a standardized internal form and *writers* presents the derived\ntransformation model in standardized formats.\n\nThe *operators* derive parameters for selected transformation techniques, for\ninstance a Helmert transformation. In case of several chained operators the later\nsteps are presented with the residuals of the earlier transformation estimate for\nwhich the current operator can attemt to reduce even further using a different\ntransformations technique.\n\n### Datasources\n\nDatasources consumes data from a single data source and provide it on a standardized\nform. The following information can be read with a datasource:\n\n    1. Station name\n    2. Coordinate tuple (x,y,z)\n    3. Uncertainty estimate of the coordinate (standard deviation)\n    4. Weight (\u003e= 0.0)\n    5. Timestamp\n\nSource and target coordinate data is handled by different datasource instances. At\nleast one datasource is needed for both source and target data sources but more than\none can be supplied for each.\n\n### Presenters\n\nPresenters deliver the resulting estimated transformation parameters in sensible\nformats. Parameters for a Helmert transformation might be presented as a\nPROJ-string, a WKT2 description and a simple text representation. A grid based\ntransformation might result in a GTG file or a more complex transformation involving\nseveral steps could be returned as a PROJ pipeline.\n\nPresenters aren't limited to only presenting the estimated parameters. A presenter\ncan also return intermediate results, residuals and various other statistics relevant\nto the transformation at hand.\n\n### Operators\n\nOperators are essential building blocks in the Transformo pipeline. All operators\nhave the ability to manipulate coordinates, generally in the sense of a geodetic\ntransformation. In addition operators *can* implement a method to derive\nparameters for said coordinate operation. Most operators do, but not all.\n\nSo, operators have two principal modes of operation:\n\n    1. Coordinate operations, as defined in the ISO 19111 terminology\n    2. Estimating parameters for the coordinate operations\n\nThe abilities of a operator are determined by the methods that enheriting classes\nimplement. *All* Operator's must implement the `forward` method and they *can*\nimplement the `estimate` and `inverse` methods. If only the `forward` method is\nimplemented the operator will exist as a coordinate operation that can't\nestimate parameters.\n\n## For developers\n\nThis section is only relevant for developers working on the software.\n\n### Installation\n\nThe installation process is similar to the one for regular users,\nalthough the installed Python environment includes essential tools\nfor development as well:\n\n```\nmamba env create -f environment-dev.yml\nmamba activate transformo-dev\npip install -e .\n```\n\nOn top of setting up a Python environment and installing the package\ndevelopers also need to set up pre-commit scripts for git:\n\n```\npre-commit install\n```\n\n### Code quality\n\nWe strive to keep the code quality in Transformo as high as possible. A number of\nmeasures has been put into place to support this. They are described in the sections\nbelow.\n\n#### Tests\n\nWe do not accept code in the main-branch that is not sufficiently tested. The\nTransformo code is tested in a Pytest test-suite. New code should come with\nsufficient tests to ensure the long-term reliability of the software. All tests\nshould be passing before merging into the main branch.\n\n#### Type annotations\n\nType annotations in Python improves readability of the code immensely and as an added\nbonus it helps IDE's improve developer workflows. In addition, Transformo relies\nheavily on the Pydantic framework which leverages type annotations to validate\nincoming data.\n\nMyPy is used to check that the types in Transformo are consistent throughout the\ncode. This can at times be a bit painful but it comes with the added benefit that it\ncan uncover errors in the code that normally wouldn't be noticed when relying on\nPythons dynamic nature.\n\n#### Pydantic\n\nBasic types in Transformo, such as `DataSource`'s and `Operators`'s, are Pydantic\n`BaseModel`'s. Pydantic is used to validate user input in a simple way, in an\nattempt to avoid problems caused by ill-formed input data. Transformo is built\non Pydantic's capability to serializee Python objects from a text source. In this\ncase the entire pipeline given in YAML format.\n\n#### Black\n\nThe code is formatted using Black. Formatting by black can be turned off in sections\nof the code where alternative formatting can be used to express the code in more\nclear terms. The most likely case for this is where mathematical formulas are turned\ninto code, for example when setting up a rotation matrix.\n\n#### Pre-commit hooks\n\nPre-commit hooks are used to enforce most of the above requirements to the code.\n\nRemember to initialize the pre-commit hooks before committing your first code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkbevers%2Ftransformo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkbevers%2Ftransformo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkbevers%2Ftransformo/lists"}