Table of Contents

Diagnose and fix: content not displayed

This article addresses common issues where virtual content cannot be displayed in planar image tracking. It provides systematic troubleshooting methods and improvement suggestions to help developers quickly locate and resolve problems.

Common causes and troubleshooting methods

Content not being displayed usually involves image recognition, feature implementation errors, or permission restrictions. The following are the main causes and troubleshooting steps:

Image recognition failure

Symptom: after the camera points at the target image, virtual content does not appear at all. Troubleshooting:

  • Check image recognition score: use the target image detection tool to upload the image and confirm the recognition score, which should reach 4-5 stars.
  • Verify image quality: ensure that the image meets the texture, size, and aspect ratio requirements in best practices.
  • Check target image entity: ensure that the surface of the target image entity, such as a poster or card, has no reflection and remains flat without folding.
  • Check logs: check application logs, search for the TargetLoad event, and confirm whether the target image was loaded successfully.

Improvement suggestions:

  • Optimize the image: increase contrast, avoid repeated patterns, and ensure that the main subject occupies more than 70% of the image.
  • Replace the image: if the problem persists after image optimization, use a test image from the official Sample, such as namecard.jpg, to verify whether the issue is caused by the image itself.
  • Ensure the physical entity: the target entity should use a matte or relatively rough surface as much as possible, and the surface should remain flat without folding or bending.
  • Check logic: ensure that the application has correctly loaded the target image used for testing.

Feature implementation errors

Symptom: the image has been recognized, but virtual content is not displayed or its position is abnormal.

Troubleshooting:

  • Check ImageTarget configuration:
    • Check whether it points to the correct file in the StreamingAssets folder according to the Source type.
    • Check whether Scale is set to the actual physical size.
  • Confirm prefab hierarchy: virtual content, such as Cube, must be a child node of ImageTarget and must not be disabled.

Improvement suggestions:

  • Reset configuration: delete and recreate ImageTarget in the scene, drag the prefab according to the specification, and bind the image.
  • Simplify the test: temporarily remove custom scripts and keep only the basic Cube to confirm the minimum runnable scene.
  • Check logs: search for errors related to ImageTargetController, such as fail to load target data.

Permission issues

Symptom: it worked normally at first, but content disappears after running for some time. Troubleshooting: Confirm whether you are in one of the following cases:

  • Using an XR headset
  • Using a custom camera
  • Using AR Engine/ARFoundation on a phone

If you are in one of the above cases, you may be using a trial License.

Improvement suggestions:

  • Use an official License.

Virtual content issues

Symptom: content is displayed normally at first, but cannot be seen when the camera is very close to or far away from the target object. Troubleshooting:

  • Check near and far clipping settings: ensure that the near and far clipping settings used when rendering virtual content are within a reasonable range.
  • Check content model size: when the content model is too large, getting close to the target object may cause clipping through the model and make the content invisible; when the content model is too small, moving away from the target object may make it too small to see clearly.

Improvement suggestions:

  • Set appropriate near and far clipping.
  • The physical size of virtual content should be appropriate compared with the target image entity.

Summary and best practices

Content not being displayed is usually caused by the image, program implementation, permissions, or the content itself. Troubleshooting is recommended in this order:

  1. Check whether the License is an official version;
  2. Check whether the virtual content itself is appropriate;
  3. Verify target image quality;
  4. Confirm whether there are issues in program implementation or development configuration.

If the problem persists, provide log files, screen recordings, and other materials through the EasyAR official forum or technical support for further analysis.