diff --git a/docs/studio/guides/xr/image-targets.mdx b/docs/studio/guides/xr/image-targets.mdx index 065b35e..32f5e1e 100644 --- a/docs/studio/guides/xr/image-targets.mdx +++ b/docs/studio/guides/xr/image-targets.mdx @@ -5,15 +5,15 @@ description: Image Targets allow you to set a flat, cylindrical or conical shape # Image Targets +:::tip +Use the [image target example project](https://github.com/8thwall/studio-image-targets-example) as a reference to get started and confirm your project structure is set up correctly. +::: + ## Introduction {frontMatter.description}



-![](/images/studio/image-target-intro.gif) - ---- - ## Enabling Image Targets To enable image targets in your project, you must use a World camera. @@ -25,80 +25,122 @@ To enable image targets in your project, you must use a World camera. ```` ---- +If you do not plan to use World Tracking in your project, you can use the **Disable World Tracking** setting to improve performance. -## Adding Image Targets +## Generating Image Target Files {#generating-image-target-files} -### Upload the Image Target +To use image targets in your project, you must generate some required assets with a command line interface (CLI). These files contain image target metadata needed by the engine. -Locate the **Image Targets** panel at the bottom left of the Studio Interface. Click on the **( + )** to add a flat, cylindrical, or conical image target. +:::tip +See [documentation on Image Target CLI](https://github.com/8thwall/8thwall/blob/main/apps/image-target-cli/README.md) for more details on cropping and cylindrical/conical image targets. +::: -````mdx-code-block - -```` +1. Open a terminal window and run `npx @8thwall/image-target-cli@latest` +2. Answer the prompts, following the examples below: -### Configuring the Image Target +```bash +Enter the path to the image file: -Customize the image target's tracking region and metadata. +~/Downloads/target1.png +``` -````mdx-code-block - -```` +```bash +Select the image type: +1) flat (default) +2) cylinder +3) cone -### Testing the Image Target +1 +``` -Scan the QR code to test the quality and tracking of your uploaded image target. +```bash +Use default crop? [Y/n]: -````mdx-code-block - -```` +y +``` -### Adding the Image Target Entity +```bash +Enter the output folder: -You can add an image target to your scene by creating an **Image Target** entity. -To do this, click **( + )** in the Scene Hierarchy and select **Image Target**. +~/Documents/8th Wall/my-project/image-targets +``` -````mdx-code-block - -```` +```bash +Enter a name for the image target: + +target1 +``` + +On generation, the following will be outputted to the specified folder: + +* Metadata within a JSON file +* Original image +* Cropped image +* Thumbnail image (263x350) +* Luminance image (grayscale, 480x640) +* Geometry image (for conical) + +:::note[Important] +Make sure the output folder was specified as a folder named `image-targets` at the root of your 8th Wall project. See [Verifying Project Structure](#verifying-project-structure) for more details. +::: -### Linking the Image Target +## Configuring Image Targets -Link the image target entity to an uploaded image target. +Create a file named `app.js` in the `src` folder (if you don't have one already). At the top of the file, configure image targets by providing paths to each image target's metadata JSON file. +```javascript +const onxrloaded = () => { + XR8.XrController.configure({ + imageTargetData: [ + require('../image-targets/target1.json'), + require('../image-targets/target2.json') + ], + }) +} +window.XR8 ? onxrloaded() : window.addEventListener('xrloaded', onxrloaded) +``` + +## Verifying Project Structure {#verifying-project-structure} + +1. Click the **Open Externally** button in the assets panel to open project code in your IDE ````mdx-code-block - + ```` ---- +2. Verify the `image-targets` folder is at the **root** of the project, and that `app.js` is within the `src` folder -## Using Image Targets +````mdx-code-block + +```` -When you add an image target to your project, an image target mesh will appear so that you can align and position other 3D content against the image target. +## Adding the Image Target Entity ---- +To add an image target to your scene: +1. Click **( + )** in the Scene Hierarchy and select **Image Target**. + +````mdx-code-block + +```` -## Simulating Image Targets +2. Select the image target entity from the scene hierarchy and enter the name of the image target in the inspector. -Studio’s **Simulator** allows you to test your image target experience remotely by simulating movement using **WASD** controls. +````mdx-code-block + +```` -### Using the Simulator with Image Targets +The name of the image target entered in the inspector should match what was entered in the CLI when generating the image target files. You can double check the name of the image target by looking at the prefix of the image target assets and/or in the JSON file associated with the image target. -To simulate movement and content placement around an image target added to your scene: +## Using Image Targets -1. Make sure your **Camera Settings** are set to **World** -2. Press **Play** to open the Simulator -3. Use the **Simulator environment options** (bottom left selector) to find your desired Image Target -4. Use the **WASD keyboard shortcuts** to simulate movement. *(You must first click on the Simulator panel before using the keyboard)* +When you add an image target to your project, an image target mesh will appear so that you can align and position other 3D content against the image target. -**Movement Keys:** +````mdx-code-block + +```` -- `W` = Forward -- `A` = Left -- `S` = Backward -- `D` = Right -- `Q` = Up -- `E` = Down +Ensure any entities you want to track to the image target are **children** of the image target entity. -Moving around the image target with WASD will trigger the **Image Found** event to simulate successful image target tracking. +````mdx-code-block + +```` \ No newline at end of file diff --git a/static/images/studio/guides/image-targets/add-image-target.png b/static/images/studio/guides/image-targets/add-image-target.png new file mode 100644 index 0000000..4d989bd Binary files /dev/null and b/static/images/studio/guides/image-targets/add-image-target.png differ diff --git a/static/images/studio/guides/image-targets/image-target-children.png b/static/images/studio/guides/image-targets/image-target-children.png new file mode 100644 index 0000000..aab0de1 Binary files /dev/null and b/static/images/studio/guides/image-targets/image-target-children.png differ diff --git a/static/images/studio/guides/image-targets/image-target-mesh.png b/static/images/studio/guides/image-targets/image-target-mesh.png new file mode 100644 index 0000000..0614385 Binary files /dev/null and b/static/images/studio/guides/image-targets/image-target-mesh.png differ diff --git a/static/images/studio/guides/image-targets/image-target-name.png b/static/images/studio/guides/image-targets/image-target-name.png new file mode 100644 index 0000000..65e500b Binary files /dev/null and b/static/images/studio/guides/image-targets/image-target-name.png differ diff --git a/static/images/studio/guides/image-targets/open-externally.png b/static/images/studio/guides/image-targets/open-externally.png new file mode 100644 index 0000000..d87ce71 Binary files /dev/null and b/static/images/studio/guides/image-targets/open-externally.png differ diff --git a/static/images/studio/guides/image-targets/project-structure.png b/static/images/studio/guides/image-targets/project-structure.png new file mode 100644 index 0000000..58af8e2 Binary files /dev/null and b/static/images/studio/guides/image-targets/project-structure.png differ diff --git a/static/images/studio/image-target-add.png b/static/images/studio/image-target-add.png deleted file mode 100644 index db83bdf..0000000 Binary files a/static/images/studio/image-target-add.png and /dev/null differ diff --git a/static/images/studio/image-target-config.png b/static/images/studio/image-target-config.png deleted file mode 100644 index 2d98335..0000000 Binary files a/static/images/studio/image-target-config.png and /dev/null differ diff --git a/static/images/studio/image-target-intro.gif b/static/images/studio/image-target-intro.gif deleted file mode 100644 index 705d67b..0000000 Binary files a/static/images/studio/image-target-intro.gif and /dev/null differ diff --git a/static/images/studio/image-target-link.png b/static/images/studio/image-target-link.png deleted file mode 100644 index c9e8e41..0000000 Binary files a/static/images/studio/image-target-link.png and /dev/null differ diff --git a/static/images/studio/image-target-upload.png b/static/images/studio/image-target-upload.png deleted file mode 100644 index ed90436..0000000 Binary files a/static/images/studio/image-target-upload.png and /dev/null differ