SIPA_RoboDK_v2.4.2 Test Package
===============================

This package contains an experimental RoboDK test update for SIPA.

Included files
--------------
1. sipa_roboDK_audit_6axis_7axis_v4.py
   Main audit script for RoboDK CSV exports.
   Current logic corresponds to SIPA RoboDK v2.4.2 behavior.

2. core/solver_fingerprint.py
   Updated solver-instability / continuity fingerprint logic,
   aligned with the v2.4.2 warning and confidence system.

3. core/root_cause.py
   Updated context-aware root-cause classifier,
   aligned with the v2.4.2 reporting logic.

Purpose
-------
This package is intended to help separate:
- true continuity / physical-consistency issues
from
- export-related jumps caused by sparse instruction-level CSVs.

It is also intended to test whether continuity / topology issues
can be screened not only in native 7-axis trajectories,
but also in standard 6-axis RoboDK exports.

What is new in v2.4.2
---------------------
- first 6-axis audit profile
- native 7-axis audit profile
- stricter CSV sanitization
- explicit 6-axis / 7-axis support boundary
- support for TIME / TIME_S columns
- support for X_TCP / Y_TCP / Z_TCP when available
- sampling-density warning with two modes:
  - instruction_level_sparsity_suspected
  - hard_gap_detected
- improved solver fingerprint interpretation
- improved context-aware root-cause classification
- deg/rad boundary warning for auto unit detection
- TCP unit assumption check for CSV Cartesian coordinates

Important note
--------------
This is an experimental test package, not yet a final release.

The 6-axis profile has been written carefully, but it still needs validation
on real RoboDK 6-axis exports.

Sparse instruction-level CSVs should be treated as screening inputs,
not as the final basis for physical conclusions.
For higher-confidence interpretation, dense time-based export is recommended.

Supported input scope
---------------------
Currently supported:
- 6-axis robot CSV exports
- 7-axis robot CSV exports

Not supported:
- other axis counts (for example true 3-axis motion systems)

If the input is outside the supported scope, the script should fail early
with a clear message instead of continuing with an invalid interpretation.

How to place the files
----------------------
Keep the following structure:

SIPA/
├── sipa_roboDK_audit_6axis_7axis_v4.py
└── core/
    ├── solver_fingerprint.py
    └── root_cause.py

Example usage
-------------
7-axis:
python sipa_roboDK_audit_6axis_7axis_v4.py --input your_7axis.csv --robot auto --unit auto

6-axis:
python sipa_roboDK_audit_6axis_7axis_v4.py --input your_6axis.csv --robot generic6 --unit auto

About unit detection
--------------------
Joint units:
- The script can auto-detect deg/rad.
- If the maximum joint magnitude is close to the deg/rad boundary,
  the script will print a warning and suggest using --unit rad manually if needed.

TCP units:
- If Cartesian TCP columns are present in the CSV,
  the script will estimate whether they look more like millimeters or meters.
- If the TCP unit is ambiguous, the script will assume millimeters by default
  and print a warning.

Sampling-density warning
------------------------
If the script detects sparse instruction-level export or large waypoint gaps,
it will emit a warning to indicate that some TCP jumps may be influenced by
export granularity rather than only by physical inconsistency.

Warning types:
- instruction_level_sparsity_suspected
- hard_gap_detected

This is especially important for:
- RoboDK CSV post-processor exports
- low-frame-count program-point CSVs
- any export that is not a dense time-sampled joint stream

Dense export recommendation
---------------------------
If possible, re-export the same program as a dense time-sampled joint stream
(for example using InstructionListJoints(..., flags=4, time_step=0.002)).

This is the preferred way to reduce export-related ambiguity and separate:
- sparse-export artifacts
from
- true continuity / physical-consistency issues

Interpretation guidance
-----------------------
7-axis:
- hidden redundancy / branch-switch continuity risks are the main target

6-axis:
- wrist-flip / posture discontinuity
- singularity-neighborhood continuity issues
- abrupt topology changes despite visually smooth TCP motion

Important:
If the input is a sparse instruction-level CSV, the result should be treated
as a screening signal, not as a final physical verdict.

Recommended workflow
--------------------
1. Run the original RoboDK export through SIPA.
2. Check whether the report raises:
   - instruction_level_sparsity_suspected
   - hard_gap_detected
3. If yes, re-export the same program as a dense time-based joint stream.
4. Re-run SIPA on the dense export.
5. Compare the two results.

If the dense export remains clean while the sparse export looks unstable,
then the earlier result was likely dominated by export granularity.

Goal
----
The goal of this package is not only to inspect 7-axis continuity,
but also to test whether 6-axis RoboDK libraries may contain continuity /
topology issues that are usually hidden inside:
- wrist flips
- singularity-neighborhood transitions
- posture discontinuities

If you generate a dense export and compare it with the original instruction-level CSV,
the result will be much easier to interpret.