Table of Contents

Diagnose and fix: content does not appear in the application

"I can see the real world, but the virtual content does not appear." This is one of the most common issues in AR development. This issue may originate from multiple stages, from Mega localization itself to your rendering logic.

This article guides you through systematically troubleshooting and resolving this issue.

Troubleshooting flow: from outside to inside

Following the principle of "external first, internal later" can efficiently locate the issue. Perform the following steps in order:

Step 1: Use external tools to verify Mega localization status (no code changes required)

Before going deep into your application code, first confirm whether the Mega localization service itself is working normally. This is the most critical step and helps you determine whether the issue is in Mega localization itself or in application development integration such as rendering.

  1. Use Mega Toolbox (mobile)

    • Install the Mega Toolbox App on your test phone, if it is not installed yet.
    • Open the App and enter On-site verification and diagnosis tool.
    • Log in to your account and select the same localization library as your application.
    • Take the phone to the same location where your application cannot display content during testing.
    • Observe the result:
      • If Toolbox localizes successfully (the interface status shows Found): congratulations. The Mega localization service is normal. The issue is inside your application, especially in rendering and content display logic. Go to Step 2.
      • If Toolbox localization fails (the interface status shows NotFound or another status): the issue is with the localization service itself. See the next section for deeper analysis.

  2. Use PC-side simulated running (if EIF has been acquired)

    • If you have recorded EIF data for this scene, you can replay the data in the Unity editor on PC using the session verification tool.
    • Observe the result:
      • If localization succeeds during replay (the interface status shows Found): the issue is in your application code or device-specific environment.
      • If localization fails during replay (the interface status shows NotFound or another status): the issue is with the localization service itself. See the next section for deeper analysis.

Step 2: Check rendering and content logic inside the application

If Step 1 confirms that the Mega localization service itself is normal, then the issue is in your application code. Check the following:

  1. Whether the content is placed under the correct node:

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

  2. Whether MegaTracker's Block Root is set correctly:

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

  3. Whether the MegaBlocks nodes have been changed:

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

  4. Whether event listening is correct:

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

  5. Headset rendering and transparency:

    • Is your virtual object occluded by other objects? Check the render queue and Shader.
    • If a VST (video see-through) device is used, check whether your rendering is correctly overlaid on the video stream.
    • If an OST (optical see-through) device is used, check whether the content is hard to see because the ambient light is too strong.

  6. Issues with the content itself:

    • Is there an issue with the Prefab you instantiate? For example, missing model files, Shader errors, scale set to 0, and so on. Try manually placing the same object in the scene and check whether it can display normally.

Analysis of common localization failure causes and improvement suggestions

If Step 1 shows that Mega Toolbox also cannot localize, carefully check and resolve localization issues. Common causes and countermeasures are as follows:

  • Cause 1: the map does not match the environment
    The on-site environment has changed greatly compared with the acquisition and mapping time, or the experience area was not covered during acquisition, or the map itself is wrong.
    Improvement suggestions:

    • Make sure the map loaded in your localization library is consistent with the current physical space in scene content.
    • If the environment has been remodeled, such as renovation or display replacement, reacquire and regenerate the map.
    • If the problematic area was not covered during acquisition and mapping, regenerate the map through incremental update.

  • Cause 2: poor initialization environment
    The application starts in an area with sparse texture, such as a solid-color wall or facing the ground.
    Improvement suggestions:

    • Guide users to start the application in an area with rich textures to help the system quickly complete initial localization.
    • Provide clear prompts in the application UI, such as "Raise the phone and look around".

  • Cause 3: network or service issues
    Network latency causes localization service requests to time out, or the localization service itself fails, or the concurrent usage limit is exceeded. For the latter cases, please give us feedback promptly.

  • Cause 4: reaching the boundary of algorithm capability
    Mega localization is based on advanced computer vision, AI, and other algorithms, but it is not omnipotent and has certain algorithm capability boundaries. When localization keeps failing in some scenes or locations, you can provide feedback to us through screen recordings, EIF data recordings, and other methods to help us continuously improve and iterate the algorithms.

In addition, note that Mega localization requires a process and usually takes about 1-2 seconds. Considering the complexity of real scenes, such as network congestion, high concurrency, phone heating and frequency reduction, this time may be longer. Therefore, you can design a clear loading/waiting page in the application to tell users "Localizing...", so users do not mistakenly think the service is down or localization cannot be found because of waiting.

Note
  • The first localization is usually slower than subsequent localizations because the system needs to load the corresponding content after the first successful localization. This is normal.
  • Moving the device quickly may cause localization loss. Guide users to move the device smoothly.

Summary and best practices

  • Always verify with external tools first: this can narrow the issue scope to "localization" or "rendering" the fastest.
  • Set reasonable user expectations: use UI prompts to let users know that localization takes time and guide them to a suitable environment.
  • Focus on content logic: make sure settings such as content binding are correct.
  • Make good use of logs: printing logs at key points, such as event triggering, pose acquisition, and response status, can help you quickly locate code logic issues.

Through the systematic troubleshooting above, you should be able to resolve most "content does not appear" issues. If the issue persists, prepare EIF data and logs, and submit a detailed report to us through Issue report.