Detected objects visibility toggle design

Background

The SDK already supports rendering detected objects through drawDetectedObjects(), but it does not provide a runtime switch to hide or show them. This design adds runtime.showDetectedObjects so callers can toggle visibility without changing detected object data.

Goal and scope

This design defines how to add a runtime visibility toggle for detected objects.

• Add runtime.showDetectedObjects with a default value of true.
• Let consumers hide and show all detected objects at runtime.
• Keep existing detected object data synchronization behavior unchanged.

Out of scope:

• Per-object visibility flags.
• New public methods for detected object visibility.
• Data deletion when visibility is turned off.

Approaches considered

This section summarizes three options and their trade-offs.

1. Recommended: manager-level runtime subscription

   • Add showDetectedObjects to runtime types and defaults.
   • Subscribe in DetectedObjectManager and toggle LAYER_DETECTED_OBJECT.visible.
   • Pros: aligns with current manager pattern, minimal code impact, no unnecessary object recreation.
   • Cons: requires one additional subscription and cleanup path.

2. MapApplication-level runtime dispatch

   • Detect runtime changes in MapApplication.updateRuntime() and call a manager method.
   • Pros: centralized runtime handling.
   • Cons: increases coupling and makes updateRuntime() heavier over time.

3. Per-object subscription in DetectedObject component

   • Each detected object subscribes to runtime visibility updates.
   • Pros: local component autonomy.
   • Cons: scales poorly with many objects and adds avoidable subscription overhead.

Selected design

The selected design uses option 1: manager-level runtime subscription.

Runtime schema and defaults

Add a new runtime field:

• RuntimeConfig.showDetectedObjects: boolean
• DEFAULT_RUNTIME_CONFIG.showDetectedObjects = true

This keeps backward compatibility because current behavior is to render detected objects by default.

Rendering control point

DetectedObjectManager becomes the single control point for this visibility state.

• On initialization, subscribe to runtime.showDetectedObjects.
• In the callback, read LAYER_DETECTED_OBJECT from AppContainer and set the layer visibility.
• Keep drawDetectedObjects() behavior unchanged for create/update/remove data flow.

This means visibility control is independent from data synchronization.

Lifecycle and cleanup

DetectedObjectManager.destroy() must also unsubscribe from the new runtime listener to avoid stale callbacks.

Impacted files

This change affects the following files.

• src/core/@types/index.d.ts
  • Add showDetectedObjects to RuntimeConfig.
• src/core/constant/config.ts
  • Add showDetectedObjects: true to DEFAULT_RUNTIME_CONFIG.
• src/core/managers/DetectedObjectManager.ts
  • Add runtime subscription and layer visibility toggle.
  • Add unsubscribe cleanup in destroy().
• src/app/debugTools/index.ts (optional)
  • Add a debug toggle action for showDetectedObjects.

Edge cases

The implementation handles these expected cases.

• If the detected object layer is not available yet, the visibility callback exits safely.
• If visibility is off and new detected object data arrives, manager data state still updates, and objects become visible immediately after toggling on.

Verification strategy

Per user request, this task does not include a dedicated test execution step.

Next steps

After this design is accepted, create an implementation plan and then apply the code changes in the impacted files.