Table of Contents

Diagnosis and repair: Issues with content not displaying in the application

"I can see the real world, but the virtual content isn't appearing." This is one of the most common issues in AR development. The problem may stem from multiple stages, from Mega positioning itself to your rendering logic.

This guide will help you systematically troubleshoot and resolve this issue.

Troubleshooting process: From external to internal

Following the principle of "external first, then internal," you can efficiently locate issues. Please perform the following steps in order:

Step one: Verify Mega positioning status using external tools (no code modification required)

Before diving into your application code, first confirm whether the Mega positioning service itself is functioning properly. This is the most critical step, as it helps determine whether the issue lies with Mega positioning itself or with rendering and other application development integration issues.

  1. Use Mega Toolbox (mobile)

    • Install the Mega Toolbox App on your test phone (if not already installed).
    • Open the app and navigate to the "Field positioning test" or similar feature.
    • Log in to your account and select the same positioning library as your application.
    • Take the phone to the same location where your application fails to display content during testing.
    • Observe the results:
      • If Toolbox positioning is successful (the interface shows Found): Congratulations! The Mega positioning service is functioning normally. The issue lies within your application, particularly in the rendering and content display logic. Proceed to step two.
      • If Toolbox positioning fails (the interface shows NotFound or other status): The issue lies with the positioning service itself. Refer to the next section for in-depth analysis.

  2. Use PC-side simulation (if EIF has been collected)

    • If you have recorded EIF data for this scenario, you can replay it using the session validation tool in the Unity editor on your PC.
    • Observe the results:
      • If positioning is successful during playback (the interface shows Found): The issue lies with your application code or device-specific environment.
      • If positioning fails during playback (the interface shows NotFound or other status): The issue lies with the positioning service itself. Refer to the next section for in-depth analysis.

Step two: Check the rendering and content logic within the application

If step one confirms that the Mega positioning service itself is functioning normally, then the issue lies in your application code. Check the following points:

  1. Is the content placed under the correct node:

    • Have you correctly placed the 3D objects under the automatically generated MegaBlocks > Block_* nodes?
    • Check the hierarchical relationship between the content and the Block nodes to ensure the virtual content is rendered in the correct position during runtime.

  2. Is the Block Root in MegaTracker set correctly:

    • Expand AR Session and check if the Block Root in Mega Tracker is the tool-generated MegaBlocks node.

  3. Has the MegaBlocks node been modified:

    • Ensure that the names of the Block_* nodes have not been altered and that none of the values in the local transform properties have been modified.

  4. Is the event listener set up correctly:

    • Have you modified the positioning callback logic in MegaTracker?
    • Does your code instantiate or display virtual content only after the successful positioning state event is triggered?

  5. Headset rendering and transparency:

    • Is your virtual object being occluded by other objects? Check the rendering queue and Shader.
    • If using a VST (video see-through) device, check if your rendering is correctly overlaid on the video stream.
    • If using an OST (optical see-through) device, check if the content is difficult to see due to excessive ambient light.

  6. Issues with the content itself:

    • Is there a problem with the prefab you instantiated? For example, missing model files, Shader errors, or scaling set to 0. Try manually placing the same object in the scene to see if it displays normally.

Common reasons for positioning failure and improvement suggestions

If Mega Toolbox also fails to locate in Step 1, you need to carefully check and resolve the positioning issue. Here are common causes and countermeasures:

  • Reason 1: Map and environment mismatch
    The on-site environment has changed significantly compared to when the map was collected, or the area being experienced was not covered during collection, or the map itself is incorrect.
    Improvement suggestions:

    • Ensure the map loaded in your positioning library matches the current physical space in terms of scene.
    • If the environment has been modified (e.g., renovation, display changes), the map needs to be recollected and regenerated.
    • If the problematic area was not covered during the initial map collection, the map should be regenerated by supplementing updates.

  • Reason 2: Poor initialization environment
    The app was launched in an area with sparse textures (e.g., plain-colored walls, facing the ground).
    Improvement suggestions:

    • Guide users to launch the app in areas with rich textures to help the system quickly complete initial positioning.
    • Provide clear prompts in the app UI, such as "Lift the phone and look around."

  • Reason 3: Network or service issues
    Network delays cause positioning service requests to time out, or the positioning service itself is malfunctioning or has exceeded the concurrent usage limit. For the latter, please provide feedback to us promptly.

  • Reason 4: Reaching algorithm capability limits
    Mega positioning is based on advanced computer vision, AI, and other algorithms, but it is not omnipotent and has certain capability limits. If persistent positioning failures occur in certain scenarios or locations, you can provide feedback to us by recording screens, capturing EIF data, etc., to help us continuously improve and iterate the algorithms.

Additionally, it is important to note that Mega positioning requires a process, typically around 1-2 seconds. Considering the complexity of real-world scenarios such as network congestion, high concurrency, and phone overheating/throttling, this time may be longer. Therefore, you can design a clear loading/waiting interface in the app to inform users that "Positioning in progress..." to avoid users mistaking the service as down or failing to locate due to waiting.

Note
  • Initial positioning is usually slower than subsequent positioning because the system needs to load corresponding content after the first successful positioning. This is normal.
  • Rapidly moving the device may cause positioning loss. Please guide users to move the device steadily.

Summary and best practices

  • Always validate with external tools first: This can quickly narrow down the issue to "positioning" or "rendering."
  • Set reasonable user expectations: Use UI cues to inform users that positioning takes time and guide them to the appropriate environment.
  • Focus on content logic: Ensure your content binding and other settings are correct.
  • Leverage logs effectively: Printing logs at key nodes (e.g., event triggers, pose acquisition, response status) can help quickly identify code logic issues.

Through the above systematic troubleshooting, you should be able to resolve most "content not displaying" issues. If the problem persists, prepare EIF data and logs, and submit a detailed report via Issue reporting.