Metadata-Version: 2.4
Name: minieye-calibration-git
Version: 0.0.7
Summary: Calibration Git repository helpers for mdrive-pb and mdrive4-json.
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: minieye-runtime-config>=0.1.1
Requires-Dist: pb-calibration>=0.2.1
Requires-Dist: transform-base>=0.0.5
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# minieye-calibration-git

Version: 0.0.7

Calibration Git helper for `mdrive_conf` and `vehicle_cfg`. The package exposes Python APIs and the `minieye-calibration-git` CLI for listing models, resolving `vehicle_id`, downloading calibration files from a resolved commit, syncing isolated checkouts, and freezing PB/JSON calibration candidates into remote branches.

Version 0.0.7 keeps complete JSON poses in the external-adjustment report even when only another calibration bucket changed. Unchanged pose axes are reported as verified zero deltas; incomplete poses retain the external classification with a `delta_issue` instead of fabricated values. For `mdrive4-json`, object-aware intrinsic classification is limited to canonical `camera<digits>.json` files; LiDAR, INS, and GNSS JSON files that change `calib_method` or other camera-intrinsic-shaped fields remain machine `格式` diagnostics instead of Feishu `内参` adjustments.

Version 0.0.6 resolves report main-tip and source references from the configured D13 remote whenever `remote_url` is available, including when it arrives only from `MINIEYE_CONFIG_FILE`. This prevents stale local checkouts from becoming report baselines. It retains calibration-type branch names, main-tip-based Git report provenance, multi-label adjustment categories, and structured six-axis external deltas for JSON and PB calibration changes.

Version 0.0.5 binds this source line to `minieye-runtime-config>=0.1.1` and keeps calibration-type branch names, main-tip-based Git report provenance, multi-label adjustment categories, and structured six-axis external deltas for JSON and PB calibration changes. The main branch comes from D13-backed `projects.<family>.git.default_branch`; final-submit resolves its fresh remote tip before creating a branch, and report URLs are pinned to commit hashes.

Final branches use `calib/{calib_type}/{vehicle_model_id}_{timestamp}`, where `calib_type` is exactly `static`, `dynamic`, or `all`. Git report adjustment labels are exactly `外参`, `内参`, `时间`, and `格式`; a changed file can carry multiple labels. External changes expose `translation_delta_m` and Euler-angle `euler_delta_deg` axes instead of raw diff lines.

Version 0.0.3 adds `final_submit_pb_calibration` and `final_submit_json_calibration`. They compare the selected candidate path with a freshly fetched remote base-branch tip. Identical content returns the base provenance with `commit_created=false` and `final_git_status=no_new_commit`; changed content uses the existing freeze abstraction to create and verify one final remote commit while retaining reference provenance. A missing path, missing branch, or moving remote baseline fails before a final branch is pushed.

Version 0.0.2 added explicit `repo_path` download, vehicle-entry resolution, worktree provenance inference, and local checkout inspection APIs so downstream packages can keep Git operations centralized here. Read APIs accept caller-controlled `snapshot_temp_dir`; when provided it takes precedence over config, which lets upstream workflow packages keep temporary Git snapshots inside their own run directory.

The Python import is `minieye_calibration_git`. The old `gitlab_get_info` package name is intentionally not provided.

## Quick Start

```python
from minieye_calibration_git import (
    download_calibration,
    final_submit_json_calibration,
    final_submit_pb_calibration,
    freeze_json_calibration,
    freeze_pb_calibration,
    list_model_infos,
    list_model_ids,
    lookup_model_by_vehicle_id,
)

models = list_model_ids("mdrive_pb")
info = list_model_infos("mdrive_pb")
model = lookup_model_by_vehicle_id("mdrive4_json", "XZT500021")
download = download_calibration(
    "mdrive4_json",
    vehicle_id="XZT500021",
    repo_vehicle_model="ECAR_HW4",
    output_dir="/tmp/calib-downloads",
)
print(info.commit, model, download.gitlab_url)

final_pb = final_submit_pb_calibration(
    vehicle_model_id="DAS_HW1_XZA000005",
    candidate_pb_path="/tmp/vehicle_config.pb.txt",
    temp_base_dir="/tmp/calib-final-submit",
)
print(final_pb.final_git_status, final_pb.final_git_url)
```

## CLI

All commands print JSON on success. Business/configuration errors print `{"ok": false, "error_type": "...", "message": "..."}` to stderr and exit with code `2`.

```bash
minieye-calibration-git list-models --family mdrive_pb --local --repo-dir /path/to/mdrive_conf
minieye-calibration-git lookup-model --family mdrive4_json --vehicle-id XZT500021 --json
minieye-calibration-git download --family mdrive_pb --vehicle-id XZA000005 --repo-vehicle-model DAS_HW1 --output-dir /tmp/out --json
minieye-calibration-git freeze-pb --vehicle-model-id DAS_HW1_XZA000005 --candidate-pb-path /tmp/vehicle_config.pb.txt --temp-base-dir /tmp/calib --remote-url git@example/repo.git --json
minieye-calibration-git freeze-json --vehicle-model-id ECAR_HW4_XZT500021 --candidate-json-dir /tmp/calib --repo-path vehicle/ECAR_HW4/XZT500021/calib --temp-base-dir /tmp/calib --remote-url git@example/vehicle_cfg.git --json
minieye-calibration-git final-submit-pb --vehicle-model-id DAS_HW1_XZA000005 --candidate-pb-path /tmp/vehicle_config.pb.txt --temp-base-dir /tmp/calib --remote-url git@example/repo.git --base-branch master
minieye-calibration-git final-submit-json --vehicle-model-id ECAR_HW4_XZT500021 --candidate-json-dir /tmp/calib --repo-path vehicle/ECAR_HW4/XZT500021/calib --temp-base-dir /tmp/calib --remote-url git@example/vehicle_cfg.git --base-branch dev_y1m4 --json
minieye-calibration-git sync --family mdrive4_json --repo-path vehicle/ECAR_HW4/XZT500021/calib --temp-base-dir /tmp/calib --json
```

## Config

The package reads `MINIEYE_CONFIG_FILE` or `~/.minieye_config/config.v1.toml` through `minieye-runtime-config>=0.1.1`.

```toml
[projects.mdrive_pb.git]
repo_dir = "/home/mini/code/minieye_git/mdrive_conf"
one_shot_download_dir = "/tmp/calib-downloads"
snapshot_temp_dir = "/tmp/minieye-calibration-git-snapshots"
remote_url = "git@git.minieye.tech:ad/mdrive/mdrive_conf.git"
default_branch = "master"
default_file_path_template = "{repo_vehicle_model}/vehicle_name/{vehicle_id}/vehicle_config.pb.txt"

[projects.mdrive4_json.git]
repo_dir = "/home/mini/code/minieye_git/vehicle_cfg"
one_shot_download_dir = "/tmp/calib-downloads"
snapshot_temp_dir = "/tmp/minieye-calibration-git-snapshots"
remote_url = "git@git.minieye.tech:ad/mdrive4/vehicle_cfg.git"
default_branch = "dev_y1m4"
default_calib_path_template = "vehicle/{repo_vehicle_model}/{vehicle_id}/calib"
tree_url_base = "https://git.minieye.tech/ad/mdrive4/vehicle_cfg"
```

Read operations default to fresh isolated snapshots and require `remote_url`. Use `fresh=False` or CLI `--local` for offline reads from the existing local commit. Python callers may pass `snapshot_temp_dir` to keep those snapshots under a caller-owned run directory; the CLI currently uses config/default snapshot locations and does not expose this override directly.

GitLab URL generation normalizes `tree_url_base` whether it is configured as the repository root, `/-/tree`, or `/-/blob` URL prefix. Download and inspect results emit commit-pinned URLs rather than branch-floating URLs.

Write operations always use independent temporary checkouts. `final-submit-*` first proves the selected remote branch, commit, and path; unchanged candidates do not create a branch, commit, or push. Changed candidates use `freeze-*`, which pushes the requested remote branch and verifies that its commit matches the local final commit. Git subprocesses are bounded to fail instead of hanging indefinitely.

## 设计原则

- [版本无关设计原则](../../design_principle.md)
