Table of Contents

Diagnosis and repair: issue of 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 can stem from multiple links, from the 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, internal later" can efficiently locate the problem. Please execute the following steps in order:

Step one: verify mega positioning status using external tools (no code modification required)

Before delving into your application code, first confirm whether the Mega positioning service itself is functioning normally. This is the most critical step, helping you determine whether the problem lies with Mega positioning itself or with application development integration issues like rendering.

  1. Using mega toolbox (mobile-side)

    • Install the Mega Toolbox App on your test phone (if not already installed).
    • Open the App, navigate to "On-site positioning test" or a similar function.
    • Log in to your account and select the same positioning library as your application.
    • Bring the phone to the same location where your application failed to display content during testing.
    • Observe the results:
      • If Toolbox positioning is successful (interface status shows Found): Congratulations! The Mega positioning service is normal. The problem lies within your application, specifically in the rendering and content display logic. Proceed to Step two.
      • If Toolbox positioning fails (interface status shows NotFound or other): The problem lies with the positioning service itself. Refer to the next section for in-depth analysis.

  2. Using PC-side simulation (if EIF has been captured)

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

Step two: check rendering and content logic within the application

If Step one confirms that the Mega positioning service itself is normal, then the problem lies within your application code. Check the following points:

  1. Is content placed under the correct node?

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

  2. Is the megaTracker's block root set correctly?

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

  3. Have the MegaBlocks nodes been modified?

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

  4. Is event listening correct?

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

  5. Headset rendering and transparency:

    • Is your virtual object being occluded by other objects? Check the render queue and Shader.
    • If using a VST (video see-through) device, check if your rendering is correctly composited on top of 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 are instantiating? For example, missing model files, shader errors, scale set to 0, etc. Try manually placing an identical object in the scene to see if it displays normally.

Analysis of common positioning failure causes and improvement suggestions

If you found in Step one that Mega Toolbox also cannot position, then you need to carefully examine and resolve the positioning issue. Here are common causes and countermeasures:

  • Cause one: map and environment mismatch
    The on-site environment has changed significantly compared to when it was captured and mapped, or the area being experienced was not covered during capture, 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 altered (e.g., renovation, replaced displays), you need to recapture and regenerate the map.
    • If the problematic area was not covered during the initial capture and mapping, you need to regenerate the map via supplemental updates.

  • Cause two: poor initialization environment
    Starting the application in a texture-poor area (e.g., plain colored walls, facing the ground).
    Improvement suggestions:

    • Guide users to start the application in texture-rich areas to help the system complete initial positioning quickly.
    • Provide clear prompts in the application UI, such as "Raise the phone and look around left and right."

  • Cause three: network or service issues
    Network latency causing positioning service requests to time out, or the positioning service itself experiencing a failure, or exceeding concurrent usage limits, etc. For the latter, please provide feedback to us promptly.

  • Cause four: reaching algorithm capability boundaries
    Mega positioning is based on advanced computer vision, AI, and other algorithms, but it is not omnipotent and has certain capability boundaries. When persistent positioning failures occur in certain scenes or points, you can provide feedback to us through screen recordings, recording 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 thermal throttling, this time may be longer. Therefore, you can design a clear loading/waiting interface in your application, informing users "Positioning in progress...", to prevent users from mistaking the service as down or failing to position due to waiting.

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

Summary and best practices

  • Always verify first with external tools: This most quickly narrows the problem scope to "positioning" or "rendering".
  • Set reasonable user expectations: Use UI prompts to let users know positioning takes time and guide them to a suitable environment.
  • Focus on content logic: Ensure your content binding and other settings are correct.
  • Utilize logs effectively: Printing logs at key nodes (e.g., event triggers, pose acquisition, response status) can help you quickly locate code logic issues.

Through the above systematic troubleshooting, you should be able to resolve the vast majority of "content not displaying" issues. If the problem persists, please prepare EIF data and logs, and submit a detailed report to us via the Issue Report method.