Inference API: add handling for (partially) unsuccessful 2d estimations

[deruyter92]

Motivation:
Previously, 2D pose predictions were always treated as successful (even when no detections were made), leaving the validation of results to the API user, or in some cases, breaking the results when no valid 2D predictions are found in all frames.

This PR introduces validation and explicit frame-level status reporting so downstream users can safely detect empty/partial outputs instead of treating low-quality predictions as successful.

Commits:
4193b92 — Adds strict 2D validation so bad/missing detections are caught early instead of silently degrading 3D results.
6edcef8 — Extends validation into 3D outputs to make prediction quality explicit and reliably propagated to callers.
58d2397 — Aligns docs/tests with the new status + frame-mask behavior so users can trust and correctly integrate the API signals.

Changes:

• The Pose2DResult and Pose3DResult now contain a property valid_frames_mask, indicating for each frame the validity of the prediction.
• A convenience method get_status_info() is made available that returns a ResultStatus (and message):
  • none valid → EMPTY
  • some valid → PARTIAL
  • all valid → SUCCESS
  • malformed data/mismatch → INVALID
  • missing/unusable mask → UNKNOWN

[Copilot]

Pull request overview

This PR improves the FMPose3D inference API by validating 2D estimator outputs and propagating frame-level validity into 3D results, so callers can reliably detect empty/partial predictions instead of treating them as fully successful.

Changes:

• Extend 2D estimators to return a valid_frames_mask and add validation/normalization of prediction shapes.
• Add ResultStatus plus status / status_message derived properties on Pose2DResult and Pose3DResult.
• Update predict() to raise on unusable 2D outputs and to mask invalid 3D frames to NaN when 2D is partial.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
fmpose3d/inference_api/fmpose3d.py	Adds frame-validity mask plumbing, status derivation, and end-to-end behavior changes for empty/partial 2D results.
tests/fmpose3d_api/test_fmpose3d.py	Updates mocks/expectations for new estimator return signature and adds status/masking assertions.
fmpose3d/inference_api/README.md	Documents new validity/status behavior and the updated estimator predict() return values.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[xiu-cs]

@deruyter92 Thanks a lot for this PR! I was aware of the potential issue in the 2D part, but I hadn't had time to fix it yet. Thanks for taking care of it!