diff --git a/README.md b/README.md index a18420d..fe90e55 100644 --- a/README.md +++ b/README.md @@ -1,163 +1,25 @@ -๏ปฟ# AWS Ambit Scenario Designer for Unreal Engine 4 +# AWS Ambit Scenario Designer for Unreal Engine 4 -The AWS Ambit Scenario Designer for Unreal Engine 4 (Ambit) plugin for Unreal Engine adds a new Mode, export to test functionality, and a new component for prototype purposes. +Welcome to **AWS Ambit Scenario Designer for Unreal Engine 4 (Ambit)**, a suite of tools to streamline 3D content creation at scale for autonomous vehicle and robotics simulation applications. From procedural placement of obstacles to automatic generation of whole cities, Ambit can help you quickly create the 3D environments and scenarios you need for your simulations or other 3D applications. -## Directory Info +![Ambit sample image](docs/readme-images/AmbitBanner.jpg) -``` -๐Ÿ“‚ Ambit/ ~ Source code for the Ambit plug-in -๐Ÿ“‚ docs/ ~ Source for Ambit documentation -๐Ÿ“‚ HoudiniDigitalAssets/ ~ Source for Houdini digital assets -๐Ÿ“„ user-guide-buildspec.yml ~ AWS CodeBuild configuration used to build the User Guide -``` - -## Developer Pre-Requisites - -- Unreal Engine 4.27 -- Visual Studio 2019 -- Houdini 18.5.696 (or higher) - -## Installation Instructions - -To use the Ambit plugin, place this repository in one of the two locations mentioned below: - -- In your Unreal Engine installation directory, under the `Engine > Plugins > Editor` folder. Choosing this method ensures the Ambit plugin is included in every Unreal Engine project you create. _Note: This is the less preferred option unless you also intend to build the engine from source._ -- If you want to include this plugin only for specific projects, add it to the `Plugins > Editor` folder for that specific Unreal project. These folders will need to be created if it doesn't already exist. - -## Dependencies - -### AWS SDK Module - -This repository contains the AWS SDK module called AWSUE4Module and pre-compiled aws-sdk-s3 libraries from [AWS SDK for C++ Version 1.9](https://github.com/aws/aws-sdk-cpp/tree/1.9.93). - -### Houdini Engine - -#### Installation - -In order to use the Houdini integration aspects of this code, you will need to download and install the Houdini Plugin (Version 2) for Unreal Engine. This plugin is bundled together with the Houdini installer on Windows. Follow these steps to get the plugin working inside Unreal Engine: - -1. Download and launch the Houdini installer. During the installation process, make sure the **Houdini Engine for Unreal** option is selected. -2. Copy the **HoudiniEngine** folder to the `Plugins > Runtime` folder of either your Unreal directory, or your Unreal project directory. -3. Launch Unreal. +Review the [User Guide](https://aws-samples.github.io/aws-ambit-scenario-designer-ue4/) to learn about Ambit's capabilities and how to start using Ambit with your projects. -For example, for UE 4.27 and Houdini 18.5.696, you will need to copy: +If you're interested in contributing to Ambit's development or would like to customize Ambit's functionality to suite your team's needs be sure to read the ["Appendix: Contributing to Ambit Development"](https://aws-samples.github.io/aws-ambit-scenario-designer-ue4/appendix-contributing/) section of the User Guide. -``` -C:\Program Files\Side Effects Software\Houdini 18.5.696\engine\unreal\4.27-v2\HoudiniEngine -``` - -to - -``` -C:\Program Files\Epic Games\UE_4.27\Engine\Plugins\Runtime\HoudiniEngine -``` - -Additional information regaring the HoudiniEngine plugin is available at: . - -#### License +Ambit is implemented as a plugin for Unreal Engine and has been tested for compatibility with Unreal Engine 4.27. -To obtain a Houdini license for Unreal Engine: - -1. Visit [this page](https://www.sidefx.com/buy/#houdini-engine-unreal-unity) in your browser. -2. Create an account and login. -3. Add the **Houdini Engine for Unreal** license to your cart and checkout. - -This license is free of cost. Once purchased, you should receive an email with next steps on setting up your Houdini Engine license. - -#### Digital Assets - -Further, you'll need to copy the file `/HoudiniDigitalAssets/AWSAmbit.hda` into the special user-specific Houdini OTL directory. On Windows you'll find this directory at `C:\Users\\Documents\houdiniXX.Y\otls`. You will need to create the `otls` folder if it doesn't exist. - -For example, for Houdini 18.5, the final file location should be: +## Repository Contents ``` -C:\Users\\Documents\houdini18.5\otls\AWSAmbit.hda +๐Ÿ“‚ Ambit/ ~ Source code for the Ambit UE4 plug-in +๐Ÿ“‚ docs/ ~ Source for Ambit documentation +๐Ÿ“‚ HoudiniDigitalAssets/ ~ Compiled HDAs for use with Ambit +๐Ÿ“„ CONTRIBUTING.md ~ Guidelines for contributing to this project +๐Ÿ“„ LICENSE ~ This project's licensing terms +๐Ÿ“„ NOTICE.md ~ Relevant copyright notices +๐Ÿ“„ THIRD_PARTY_LICENSES.md ~ Licenses for 3rd party assets used in this project +๐Ÿ“„ user-guide-buildspec.yml ~ AWS CodeBuild configuration used to build the User Guide ``` -### glTF Exporter Plugin - -The glTF Exporter Plugin needs to be installed to Unreal Engine in order to work with the Ambit plugin and to export any static meshes as glTF. There are two ways to install the plugin to your Unreal Engine version: - -- Using your preferred internet browser. -- Using the Epic Games Launcher. - -#### Using the browser - -1. Visit [this link](https://www.unrealengine.com/marketplace/en-US/product/gltf-exporter) in your browser. -2. If you aren't already signed in, Click on the **Sign in to Buy** button to login to the marketplace using your Epic Games ID. -3. Once signed in, click on the **Install to Engine** button and select the engine version before proceeding. - -#### Using the Epic Games Launcher - -1. Open the **Epic Games Launcher** -2. Click on the **Marketplace** tab at the top of the launcher. -3. Search for "gltf exporter" and open the plugin made by **Epic Games** -4. Click on the **Install to Engine** button and select the engine version before proceeding. - -## Build Instructions - -Once the Ambit plugin is installed in the desired location, head over to your Unreal Engine project and right-click on the `*.uproject` file at the root of the project directory and select the **Generate Visual Studio project files** option. Select the appropriate engine version if required and proceed with generating the files. - -Once completed, launch the `*.sln` file in Visual Studio. In the **Solution Explorer** window, right-click on your project and select **Set as Startup Project**. To build the solution, select `Build > Build Solution` from the Visual Studio menubar. - -To launch the project, hit the **Local Windows Debugger** button, or press **F5**. - -You can also launch the project by opening the `*.uplugin` file present at the root of your project directory. - -## Package instructions - -To create pre-built binaries of the plugin, follow these steps: - -1. Please make sure dependencies of Ambit plugin are set up in the **Engine folder** before going to the next step. -2. Click **Edit** tab and open **Plugins** window. -3. Find the **AWS Ambit Scenario Designer** plugin. -4. Click the **Package** button and choose the folder you would like to save the plugin. -5. Wait for the packaging process to complete and use the **Output Log** to see logs. - -You can use this pre-built plugin in both Unreal Engine C++ and Blueprint Projects by installing it in your Project Plugins folder or the Engine Plugins folder. - -## Testing instructions - -### Testing Ambit Spawners - -To manually test the **Ambit Spawners**, open and run the map found at `/Ambit Content/Test/Maps/ProceduralPlacementTestMap` and use the existing **Spawn on Surface** actor. - -### Testing Import/Export - -To manually test import and export functionality, follow these steps: - -1. First set some random parameters in the **Scenario Settings** section of the Ambit Mode. -2. Click the "Export Scenario" Button at the bottom of the **Scenario Settings** section. -3. Verify the file was created in the **Project Folder** of your project. -4. Reset all the values of your **Scenario Settings** section or re-load the project. -5. Click the '...' next to **Scenario Name** and import the file. - -### Running Automated Tests - -To enable the Unreal Engine editor to support automated tests, open the Unreal Engine project, enable the plugin called "Functional Testing Editor", and restart the editor. - -Automated test files - called "specs" - end with a ".spec.cpp" file extension and are usually located next to the files that they test. These tests will be automatically recognized by the Unreal Engine test runner. To run the tests: - -1. First open the **Test Automation** window (`Window > Test Automation`). -2. Select the **Automation** tab. -3. Tick the box next to the **Ambit** group of tests. -4. Click the **Start Tests** button. - -For more info on working with automated tests in UE see ["Automation Spec Overview"](https://docs.unrealengine.com/en-US/Programming/Automation/AutomationSpec/index.html) - -## User Guide - -To learn how to use the Ambit plugin, you can take a look at the [User Guide](https://aws-samples.github.io/aws-ambit-scenario-designer-ue4/). This guide will help you learn how to use the various aspects of the Ambit plugin such as the AWS Ambit Scenario Mode, its weather and scenario generation options, along with the Ambit Spawner and Ambit Path Generation tools. - -To contribute to the User Guide, follow the instructions listed [here](./docs/user-guide/README.md). - -Meanwhile, you can use the In-Editor tutorials to get familiar with AWS Ambit Scenario Mode. Click the tutorial button at the top right corner of the Unreal Editor or the top right corner of the AWS Ambit Scenario Mode and select the **AWS Ambit** chapter to view all tutorials. - -## Other Information - -| File | Description | -| ----- | ----- | -| CONTRIBUTING.md | All the information you need to know if you would like to contribute to this project | -| LICENSE | Covers the license information for this project | -| NOTICE.md | Amazon.com, Inc.'s copyright for this project | -| THIRD_PARTY_LICENSES.md | Contains a list of assets obtained from third parties | diff --git a/docs/readme-images/AmbitBanner.jpg b/docs/readme-images/AmbitBanner.jpg new file mode 100644 index 0000000..10eaae5 Binary files /dev/null and b/docs/readme-images/AmbitBanner.jpg differ diff --git a/docs/user-guide/docs-source/appendix-contributing.md b/docs/user-guide/docs-source/appendix-contributing.md new file mode 100644 index 0000000..a7bfa95 --- /dev/null +++ b/docs/user-guide/docs-source/appendix-contributing.md @@ -0,0 +1,108 @@ +# Appendix: Contributing to Ambit Development + +This section provides important information for anyone who would like to contribute to the development of the Ambit tools or to make custom modifications to Ambit for their own purposes. It covers technical setup and developer workflow. For general contributing guidelines and process, see the repository's [CONTRIBUTING](https://github.com/aws-samples/aws-ambit-scenario-designer-ue4/blob/main/CONTRIBUTING.md) file. + +> โœ๏ธ This guide assumes you already have Unreal Engine development experience. + + + +## Setup + +Ensure you have completed the main [Setup > Initial Setup (One-Time)](../setup/#initial-setup-one-time) instructions from this user guide. + +In addition to having Unreal Engine 4.27 installed, you will also need the Microsoft Visual Studio development tools required for UE4 C++ development. If you need help with these setup steps, refer to the Unreal Engine 4 documentation, especially ["Setting Up Visual Studio for Unreal Engine"](https://docs.unrealengine.com/4.26/en-US/ProductionPipelines/DevelopmentSetup/VisualStudioSetup/). + +Create a new Unreal Engine C++ project to use as a host project while you work on Ambit development. The only configuration requirements for this project is that you designate it as a C++ project rather than a Blueprint project when prompted. Otherwise, you can keep all other project configuration settings at their defaults or change them to your liking. + +Create a "Plugins" folder at the root of your UE project folder. Clone the [Ambit repository](https://github.com/aws-samples/aws-ambit-scenario-designer-ue4) into the "Plugins" folder. The result will look like this... + +`\Plugins\aws-ambit-scenario-designer-ue4\` + +Once the Ambit plugin repository has been cloned, right-click on the `*.uproject` file at the root of the project directory and select the "Generate Visual Studio project files" option. Select the appropriate engine version if required. A new Visual Studio solution file (`*.sln`) will be generated for you. + +Launch your sample project by clicking on the `*.uproject` file. When prompted to rebuild missing modules, click "Yes". + +![Missing Modules prompt](images/appendix/RebuildMissingModules.png) + +Next, you'll need to enable some plugins to support running automated tests. Once the project opens, enable the following plugins: + +- Functional Testing Editor +- Runtime Tests +- Editor Tests + +Restart (or simply close) the editor for the plugins to take effect. + + + +## Development Workflow + +Follow this workflow when making changes to the Ambit C++ code... + +1. Launch the project's `*.sln` file in Visual Studio. +2. In the **Solution Explorer** window, right-click on your project and select **Set as Startup Project**. +3. Make your code edits. +4. Compile and run the solution through either of these methods: + - To build only: Select `Build > Build Solution` from the Visual Studio menubar + - To build and run: Press the **Local Windows Debugger** button (or press **F5**). +5. Repeat steps 3-4 as needed. + + + +## Testing + +### Running Automated Tests + +The Ambit plugin includes a number of automated tests. Automated test files, called "specs", end with a `*.spec.cpp` file extension and are usually located next to the files that they test. These tests will be automatically recognized by the Unreal Engine test runner. To run the tests: + +1. First open the **Test Automation** window (`Window > Test Automation`). +2. Select the **Automation** tab. +3. Tick the box next to the **Ambit** group of tests. +4. Click the **Start Tests** button. + +> ๐Ÿ’ก **Tip:** For more info on working with automated tests in UE see ["Automation Spec Overview"](https://docs.unrealengine.com/en-US/Programming/Automation/AutomationSpec/index.html) + +### Test Maps + +A sample map is provided to aid in manual testing of the various Ambit spawner actors: + + `/Ambit Content/Test/Maps/ProceduralPlacementTestMap` + +A sample map is provided to aid in manual testing of the Environment FX actor: + +`Ambit Content/EnvironmentFX/TestMap/TestWeatherMap` + +### Testing Scenario Import/Export + +To manually test scenario import and export functionality, follow these steps: + +1. First set some random parameters in the **Scenario Settings** section of the Ambit Mode. +2. Click the "Export Scenario" Button at the bottom of the **Scenario Settings** section and save the `*.sdf.json` file. +3. Verify the file was created in the destination location you specified. +4. Reset all the values of your **Scenario Settings** section or re-load the project. +5. Click the `...` next to **Scenario Name** and import the `*.sdf.json` file. +5. Confirm that all settings were restored as expected. + + + +## Packaging a Release Build + +To create a packaged version of the plugin for distribution, follow these steps: + +1. Click the **Edit** tab and open **Plugins** window. +2. Find the **AWS Ambit Scenario Designer** plugin. +3. Click the **Package** button and choose the folder to which you would like to save the plugin. +4. Wait for the packaging process to complete and use the **Output Log** panel to check for any warnings or errors. + +You can use this pre-built plugin in both Unreal Engine C++ and Blueprint Projects by installing it in your project's "Plugins" folder or the Engine "Plugins" folder. + + + +## Contributing to the User Guide + +To contribute to the User Guide, follow the instructions listed [here](https://github.com/aws-samples/aws-ambit-scenario-designer-ue4/blob/main/docs/user-guide/README.md). + + + +## Dependencies + +The Ambit plugin uses a subset of the AWS SDK for C++ to communicate with AWS services. A precompiled version of these libraries ([Version 1.9](https://github.com/aws/aws-sdk-cpp/tree/1.9.93)) has been included in this repository and encapsulated as a module called "AWSUE4Module". \ No newline at end of file diff --git a/docs/user-guide/docs-source/aws-setup.md b/docs/user-guide/docs-source/aws-setup.md index f87af13..326b3b7 100644 --- a/docs/user-guide/docs-source/aws-setup.md +++ b/docs/user-guide/docs-source/aws-setup.md @@ -4,14 +4,14 @@ Ambit integrates with [Amazon Simple Storage Service (Amazon S3)](https://docs.a ## Setup -To successfully utilize the S3 bucket, AWS credentials need to be configured in your environment for a role that has access to the S3 bucket. Follow [this guide](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html) for step-by-step instructions. +To successfully utilize an S3 bucket, AWS credentials need to be configured in your environment for a role that has access to the S3 bucket. Follow [this guide](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html) for step-by-step instructions. ## Configure AWS Settings -Once the account has the correct permissions, find the **AWS Settings** menu inside of **AWS Ambit Scenario Mode**, then select the AWS Region of your S3 bucket and input the bucket name. +Once the account has the correct permissions, find the **AWS Settings** menu inside of **AWS Ambit Scenario Mode**, then select the AWS region of your S3 bucket and input the bucket name. If the bucket doesn't already exist it will be automatically created for you. -> **Note:** S3 bucket names must adhere to the [S3 Bucket Naming Rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) +> **Note:** S3 bucket names must adhere to the [bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) ![Locating the AWS Settings](./images/aws-settings/AwsSettingsMenu.png) -Ambit will utilize this setting throughout to upload and download from the bucket specified. Ambit will automatically create a S3 bucket if one does not exist when uploading. +Ambit will utilize this setting throughout to upload and download from the bucket specified. diff --git a/docs/user-guide/docs-source/building-generator.md b/docs/user-guide/docs-source/building-generator.md new file mode 100644 index 0000000..5dbee23 --- /dev/null +++ b/docs/user-guide/docs-source/building-generator.md @@ -0,0 +1,16 @@ +![Ambit Building Generator output](./images/city-generation/BuildingGeneratorOutput.jpg) + +## Using the Ambit Building Generator + +Using the UE editor's Content Browser, navigate to the _**Ambit Content > ProceduralTools**_ folder. Then, right-click on the **AmbitBuildingGenerator** and select **"Instantiate at the origin"**. + +> โœ๏ธ **Note:** If you don't see the **Ambit Content** folder listed in the Content Browser you will need to enable the "Show Plugin Content" option using the Content Browser's View Options menu. ![View Options menu](images/city-generation/ViewOptionsMenu.png) You may also need to toggle the "Show/Hide Sources Panel" icon. ![Show Sources icon](images/city-generation/ShowSourcesIcon.png) + +There will be a small delay while the Houdini Engine starts in the background and then initializes the asset. + +Ensure that the new **AmbitBuildingGenerator** instance is selected in the World Outliner panel. Then, find the section of the Details panel titled _**Houdini Parameters**_. Import an OSM file that you downloaded previously by clicking the `โ€ฆ` icon next to the _**OSM File**_ parameter field. + +![OSM File parameter](images/city-generation/BuildingGen_OSMParam.png) + +Building generation will start automatically. Generation could take several minutes depending on the size and complexity of the OSM building data. + diff --git a/docs/user-guide/docs-source/city-generation.md b/docs/user-guide/docs-source/city-generation.md new file mode 100644 index 0000000..4d7b51c --- /dev/null +++ b/docs/user-guide/docs-source/city-generation.md @@ -0,0 +1,11 @@ +Ambit provides two tools which aid in the creation of complex real-world environments - **Ambit Building Generator** and **Ambit Road Generator**. These tools accept any [Open Street Map](https://www.openstreetmap.org/#map=17/47.61388/-122.33799) (OSM) file as input and generate 3D geometry that is simulation-ready. + +> โš ๏ธ **Important:** These tools leverage the Houdini Engine. Be sure you have installed both the Houdini Engine and the Houdini plugin for Unreal before using these tools. See the [Setup](../setup) section of this user guide for instructions. + +The **Ambit Building Generator** produces stylized buildings based on the building shapes contained in the OSM file. + +![Ambit Building Generator output](./images/city-generation/BuildingGeneratorOutput.jpg) + +The **Ambit Road Generator** produces roadways, complete with road markings, based on the road descriptions contained in the OSM file. + +![Ambit Road Generator output](./images/city-generation/RoadGeneratorOutput.jpg) \ No newline at end of file diff --git a/docs/user-guide/docs-source/css/extra.css b/docs/user-guide/docs-source/css/extra.css index bd12f1e..31d0a18 100644 --- a/docs/user-guide/docs-source/css/extra.css +++ b/docs/user-guide/docs-source/css/extra.css @@ -7,4 +7,10 @@ number-badge { height: 1.5em; border-radius: 100px; text-align: center; +} + +blockquote p { + color: #959595; + background-color: #f4f4f4; + padding: .5em .7em; } \ No newline at end of file diff --git a/docs/user-guide/docs-source/images/AmbitBanner.jpg b/docs/user-guide/docs-source/images/AmbitBanner.jpg new file mode 100644 index 0000000..10eaae5 Binary files /dev/null and b/docs/user-guide/docs-source/images/AmbitBanner.jpg differ diff --git a/docs/user-guide/docs-source/images/appendix/RebuildMissingModules.png b/docs/user-guide/docs-source/images/appendix/RebuildMissingModules.png new file mode 100644 index 0000000..8d94991 Binary files /dev/null and b/docs/user-guide/docs-source/images/appendix/RebuildMissingModules.png differ diff --git a/docs/user-guide/docs-source/images/city-generation/BuildingGen_OSMParam.png b/docs/user-guide/docs-source/images/city-generation/BuildingGen_OSMParam.png new file mode 100644 index 0000000..32594f0 Binary files /dev/null and b/docs/user-guide/docs-source/images/city-generation/BuildingGen_OSMParam.png differ diff --git a/docs/user-guide/docs-source/images/city-generation/BuildingGeneratorOutput.jpg b/docs/user-guide/docs-source/images/city-generation/BuildingGeneratorOutput.jpg new file mode 100644 index 0000000..07f05b4 Binary files /dev/null and b/docs/user-guide/docs-source/images/city-generation/BuildingGeneratorOutput.jpg differ diff --git a/docs/user-guide/docs-source/images/city-generation/RoadGen_OSMParam.png b/docs/user-guide/docs-source/images/city-generation/RoadGen_OSMParam.png new file mode 100644 index 0000000..58ca0fa Binary files /dev/null and b/docs/user-guide/docs-source/images/city-generation/RoadGen_OSMParam.png differ diff --git a/docs/user-guide/docs-source/images/city-generation/RoadGeneratorOutput.jpg b/docs/user-guide/docs-source/images/city-generation/RoadGeneratorOutput.jpg new file mode 100644 index 0000000..104dfec Binary files /dev/null and b/docs/user-guide/docs-source/images/city-generation/RoadGeneratorOutput.jpg differ diff --git a/docs/user-guide/docs-source/images/city-generation/ShowSourcesIcon.png b/docs/user-guide/docs-source/images/city-generation/ShowSourcesIcon.png new file mode 100644 index 0000000..73db5a8 Binary files /dev/null and b/docs/user-guide/docs-source/images/city-generation/ShowSourcesIcon.png differ diff --git a/docs/user-guide/docs-source/images/city-generation/ViewOptionsMenu.png b/docs/user-guide/docs-source/images/city-generation/ViewOptionsMenu.png new file mode 100644 index 0000000..8169ead Binary files /dev/null and b/docs/user-guide/docs-source/images/city-generation/ViewOptionsMenu.png differ diff --git a/docs/user-guide/docs-source/images/home/AmbitPlugin.png b/docs/user-guide/docs-source/images/home/AmbitPlugin.png deleted file mode 100644 index 99536ec..0000000 Binary files a/docs/user-guide/docs-source/images/home/AmbitPlugin.png and /dev/null differ diff --git a/docs/user-guide/docs-source/images/home/EnableAmbitMode_426.png b/docs/user-guide/docs-source/images/home/EnableAmbitMode_426.png deleted file mode 100644 index 02f347c..0000000 Binary files a/docs/user-guide/docs-source/images/home/EnableAmbitMode_426.png and /dev/null differ diff --git a/docs/user-guide/docs-source/images/home/EnablePluginContent.png b/docs/user-guide/docs-source/images/home/EnablePluginContent.png deleted file mode 100644 index a1d1a44..0000000 Binary files a/docs/user-guide/docs-source/images/home/EnablePluginContent.png and /dev/null differ diff --git a/docs/user-guide/docs-source/images/home/PlaceActors_ContentBrowser.png b/docs/user-guide/docs-source/images/home/PlaceActors_ContentBrowser.png deleted file mode 100644 index e153dd6..0000000 Binary files a/docs/user-guide/docs-source/images/home/PlaceActors_ContentBrowser.png and /dev/null differ diff --git a/docs/user-guide/docs-source/images/home/PluginDropdown.png b/docs/user-guide/docs-source/images/home/PluginDropdown.png deleted file mode 100644 index 6e66d12..0000000 Binary files a/docs/user-guide/docs-source/images/home/PluginDropdown.png and /dev/null differ diff --git a/docs/user-guide/docs-source/images/home/SourcePanel.png b/docs/user-guide/docs-source/images/home/SourcePanel.png deleted file mode 100644 index d39f7da..0000000 Binary files a/docs/user-guide/docs-source/images/home/SourcePanel.png and /dev/null differ diff --git a/docs/user-guide/docs-source/images/setup/HoudiniInstall_1.1.png b/docs/user-guide/docs-source/images/setup/HoudiniInstall_1.1.png new file mode 100644 index 0000000..108359b Binary files /dev/null and b/docs/user-guide/docs-source/images/setup/HoudiniInstall_1.1.png differ diff --git a/docs/user-guide/docs-source/images/setup/HoudiniInstall_1.png b/docs/user-guide/docs-source/images/setup/HoudiniInstall_1.png new file mode 100644 index 0000000..88eb045 Binary files /dev/null and b/docs/user-guide/docs-source/images/setup/HoudiniInstall_1.png differ diff --git a/docs/user-guide/docs-source/images/setup/HoudiniInstall_2.png b/docs/user-guide/docs-source/images/setup/HoudiniInstall_2.png new file mode 100644 index 0000000..44c78d8 Binary files /dev/null and b/docs/user-guide/docs-source/images/setup/HoudiniInstall_2.png differ diff --git a/docs/user-guide/docs-source/images/setup/HoudiniInstall_3.png b/docs/user-guide/docs-source/images/setup/HoudiniInstall_3.png new file mode 100644 index 0000000..7ff288d Binary files /dev/null and b/docs/user-guide/docs-source/images/setup/HoudiniInstall_3.png differ diff --git a/docs/user-guide/docs-source/images/setup/HoudiniInstall_4.png b/docs/user-guide/docs-source/images/setup/HoudiniInstall_4.png new file mode 100644 index 0000000..db6d33d Binary files /dev/null and b/docs/user-guide/docs-source/images/setup/HoudiniInstall_4.png differ diff --git a/docs/user-guide/docs-source/images/setup/ShowHideSourcesIcon.png b/docs/user-guide/docs-source/images/setup/ShowHideSourcesIcon.png new file mode 100644 index 0000000..ddb1bea Binary files /dev/null and b/docs/user-guide/docs-source/images/setup/ShowHideSourcesIcon.png differ diff --git a/docs/user-guide/docs-source/images/setup/ShowPluginContent.jpg b/docs/user-guide/docs-source/images/setup/ShowPluginContent.jpg new file mode 100644 index 0000000..66b6c72 Binary files /dev/null and b/docs/user-guide/docs-source/images/setup/ShowPluginContent.jpg differ diff --git a/docs/user-guide/docs-source/index.md b/docs/user-guide/docs-source/index.md index 472700c..9fa51ff 100644 --- a/docs/user-guide/docs-source/index.md +++ b/docs/user-guide/docs-source/index.md @@ -1,37 +1,16 @@ # Welcome to AWS Ambit Scenario Designer for Unreal Engine 4 -AWS Ambit Scenario Designer for Unreal Engine 4 (Ambit) is a suite of tools to streamline content creation at scale for autonomous vehicle and robotics simulation applications. +AWS Ambit Scenario Designer for Unreal Engine 4 (Ambit) is a suite of tools to streamline 3D content creation at scale for autonomous vehicle and robotics simulation applications. From procedural placement of obstacles to automatic generation of whole cities, Ambit can help you quickly create the 3D environments and scenarios you need for your simulations or other 3D applications. -Currently Ambit can be installed as a plugin for [Unreal Engine 4.27](https://docs.unrealengine.com/en-US/Support/Builds/ReleaseNotes/4_27/index.html). +![Ambit sample image](images/AmbitBanner.jpg) -## Getting Started +Ambit is implemented as a plugin for the Windows version of Unreal Engine 4 (UE4). However, the content you create with Ambit can be exported and used with other versions of UE4 (Mac, Linux) or even non-UE4 simulators and 3D tools. -You can install the plugin either directly in the engine folder (in "Engine/Plugins/Editor/Ambit") or in your project folder (in "Plugins/Editor/Ambit"). +Ambit has been tested for compatibility with [Unreal Engine 4.27](https://docs.unrealengine.com/en-US/Support/Builds/ReleaseNotes/4_27/index.html). -Make sure the Ambit plugin is installed and enabled in your Unreal Engine installation by going to **Edit** -> **Plugins** and ensuring the **enabled** checkbox for Ambit is checked. -![Plugins Dropdown](./images/home/PluginDropdown.png) -![Plugin Menu Enabled](./images/home/AmbitPlugin.png) +> ๐Ÿ“ฃ **Attention:** During the usage of this plugin tool Ambit will collect generic metrics to inform AWS about usage patterns and performance of Ambit's individual features. These metrics contain no personally identifiable information and are not shared or transferred. +> +> If you prefer to opt out from this metrics collection you can do so by making a small code modification and compiling the Ambit plugin from source. Within the Ambit plugin folder, edit the C++ header file `Source/Ambit/Utils/UserMetricsSubsystem.h` to make the `RecordUserMetrics` field false. Full details on how to compile Ambit from source can be found in ["Appendix: Contributing to Ambit Development"](appendix-contributing/). -## AWS Ambit Scenario Mode - -Once the plugin is enabled a new **AWS Ambit Scenario Mode** will be added to the **Modes** dropdown menu in the top panel. Select this Mode to enable scenario generation for your scene. - -![Modes Dropdown](./images/home/EnableAmbitMode_426.png) - -## Enabling Content - -Once the Ambit plugin is installed and enabled you will need to enabled plugin content in your content browser to access some of Ambit's tools. To do this, go to the **View Options** dropdown in the bottom right hand corner of your content browser and select **"Show Plugin Content"**. - -![Plugin Content Menu Enabled](./images/home/EnablePluginContent.png) - -Then "Ambit Content" folder should be selected in the "Sources Panel" of the Content Browser. - -![Source Panel Enabled](./images/home/SourcePanel.png) - -## Note - -During the usage of this plugin tool, Ambit may collect generic user metrics to inform us about the usage of this plugin tool. These metrics contain no identifiable info and are not shared or transferred. - -If you prefer to opt out from this metrics collection, within the Ambit plugin folder, you can edit the C++ header file Source/Ambit/Utils/UserMetricsSubsystem.h to make the RecordUserMetrics field false. diff --git a/docs/user-guide/docs-source/obtaining-osm.md b/docs/user-guide/docs-source/obtaining-osm.md new file mode 100644 index 0000000..208a056 --- /dev/null +++ b/docs/user-guide/docs-source/obtaining-osm.md @@ -0,0 +1,5 @@ +## Obtaining an OpenStreetMap File + +OpenStreetMap files representing any location in the world can be exported directly from the [OpenStreetMap website](https://www.openstreetmap.org/). + +Note that the number and size of buildings contained in the map area will impact how long the Ambit tools take to process the map. When trying the tools for the first time, we recommend using a map area that is equivalent to a few city blocks square (roughly 2,000 ft. by 2,000 ft.) or smaller. \ No newline at end of file diff --git a/docs/user-guide/docs-source/road-generator.md b/docs/user-guide/docs-source/road-generator.md new file mode 100644 index 0000000..c1b9646 --- /dev/null +++ b/docs/user-guide/docs-source/road-generator.md @@ -0,0 +1,17 @@ +![Ambit Road Generator output](./images/city-generation/RoadGeneratorOutput.jpg) + +## Using the Ambit Road Generator (Experimental) + +> ๐Ÿงช The Ambit Road Generator is currently considered experimental. There are many types of road configurations that it doesn't handle well at the moment. + +Using the UE editor's Content Browser, navigate to the _**Ambit Content > ProceduralTools**_ folder. Then, right-click on the **AmbitRoadGenerator** and select **"Instantiate at the origin"**. + +> โœ๏ธ **Note:** If you don't see the **Ambit Content** folder listed in the Content Browser you will need to enable the "Show Plugin Content" option using the Content Browser's View Options menu. ![View Options menu](images/city-generation/ViewOptionsMenu.png) You may also need to toggle the "Show/Hide Sources Panel" icon. ![Show Sources icon](images/city-generation/ShowSourcesIcon.png) + +There will be a small delay while the Houdini Engine starts in the background and then initializes the asset. + +Ensure that the new **AmbitRoadGenerator** instance is selected in the World Outliner panel. Then, find the section of the Details panel titled _**Houdini Parameters**_. Import an OSM file that you downloaded previously by clicking the `โ€ฆ` icon next to the _**OSM File**_ parameter field. + +![OSM File parameter](images/city-generation/RoadGen_OSMParam.png) + +Road generation will start automatically. Generation time may range from a few seconds to a few minutes. \ No newline at end of file diff --git a/docs/user-guide/docs-source/setup.md b/docs/user-guide/docs-source/setup.md new file mode 100644 index 0000000..9deda29 --- /dev/null +++ b/docs/user-guide/docs-source/setup.md @@ -0,0 +1,123 @@ +# Setup + + + +## Initial Setup (One-Time) + +Complete the following setup before using Ambit for the first time. + +> โฑ Initial setup takes about 20 minutes. + +> ๐Ÿ›‘ Ambit is implemented as a plugin for the Windows version of Unreal Engine 4 (UE4). Therefore, Windows is required. However, the content you create with Ambit can be exported and used with other versions of UE4 (Mac, Linux) or even non-UE4 simulators and 3D tools. + +> ๐Ÿ›‘ These instructions assume you already have Unreal Engine 4.27 installed. If you don't, you can [download Unreal Engine for free](https://www.unrealengine.com/en-US/download). Choose the Unreal Engine license that is appropriate for your team. Ambit will work with any Unreal Engine license. + +### 1. Download the Ambit plugin for UE4 + +Download the latest pre-built release of the Ambit UE4 plugin from the GitHub [Releases section](https://github.com/aws-samples/aws-ambit-scenario-designer-ue4/releases). + +Unzip the file you downloaded. You may unzip it to any location that's convenient for you. It will unzip as a folder named "AwsAmbit". + +We'll return to the Ambit plugin in later steps. + +### 2. Install the AWS Command Line Interface + +You will be configuring your computer to communicate with AWS services. The easiest way to do this is by installing the AWS Command Line Interface (AWS CLI). + +Install the AWS CLI to your local computer following the ["Install/Update" instructions on this page](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). (You can ignore the "Next steps" section at the bottom of that page.) + +### 3. Create AWS credentials for use with Ambit + +Ambit integrates with Amazon's cloud storage service, [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html). To enable this integration, you will need to provide AWS credentials that allow access to Amazon S3. + +The easiest way to generate these credentials is to create a new AWS Identity Access & Management (IAM) user in your AWS account. [Follow this guide](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html) to create a new IAM user having **AmazonS3FullAccess** permissions. + +### 4. Install Houdini Engine for UE4 + +Some Ambit functionality leverages the **Houdini Engine**, a 3D content creation tool from SideFX. There are many flavors of Houdini available including a free version called "Houdini Engine for Unreal". That is the version we will use with Ambit. + +Acquire a free license for Houdini Engine for Unreal by clicking the relevant "Add To Cart" button on [this web page](https://www.sidefx.com/buy/#houdini-engine-unreal-unity) and completing the checkout process. + +Download and install the "Houdini Launcher" from the [SideFX download page](https://www.sidefx.com/download/). + +Once installed, launch the Houdini Launcher. + +Click the 1 "Install" button and select 2 the latest "Production Build" of Houdini 19.0.x. + +![Houdini Launcher annotated](images/setup/HoudiniInstall_1.png) + +When prompted with the Preferences dialog keep the default settings and enable the 3 "Unreal Plug-In" and 4 "Automatically Install SideFX Labs" options, then click 5 "Save". + +![Houdini Launcher License Tab](images/setup/HoudiniInstall_1.1.png) + +Once installation completes click on the 6 "Licenses" tab. Then click the 7 "License Administrator" button. + +![Houdini Launcher License Tab](images/setup/HoudiniInstall_2.png) + +Two windows will appear. The "Entitlements" window should display your available "Houdini Engine for Unity/Unreal" licenses. Set the 8 "Quantity" value to "1" and click the 9 "Install" button. + +![Houdini Administrator Entitlements](images/setup/HoudiniInstall_3.png) + +The remaining Houdini Administrator window should now reflect that you've successfully configured your Houdini license. You may close both this window and the Houdini Launcher. + +![Houdini Administrator complete](images/setup/HoudiniInstall_4.png) + +Next, you'll add the Houdini Engine plugin to your Unreal Engine install. Do this by copying the "HoudiniEngine" folder from... + +`C:\Program Files\Side Effects Software\Houdini Engine\Unreal\19.0.x\4.27\HoudiniEngine` + +...to the following location... + +`C:\Program Files\Epic Games\UE_4.27\Engine\Plugins\Runtime\HoudiniEngine` + + + +### 4. Add the AWSAmbit.hda to your Houdini Engine install + +The final part of setting up Houdini Engine is to copy one of the Ambit plugin files to your Houdini install folder. Recall that you downloaded the Ambit plugin in step 1. Find this file... + +`[AwsAmbit plugin folder]\AWSAmbit.hda` + +...and copy it to the following location, creating the "otls" directory if necessary... + +`C:\Users\[username]\Documents\houdini19.0\otls\AWSAmbit.hda` + + + +### 5. Install the glTF Exporter UE4 plugin + +Some of Ambit's export functionality relies on the **glTF Exporter plugin** from Epic Games. This plugin doesn't ship with Unreal Engine but can be downloaded for free from the Unreal Engine Marketplace following the steps below. + +Visit the [glTF Exporter Marketplace web page](https://www.unrealengine.com/marketplace/en-US/product/gltf-exporter). + +If not already signed in, click the "Sign in to Buy" button and log in. + +Once logged in, click the "Open in Launcher" button. This will take you to the same asset page in the Marketplace tab of the Epic Games Launcher. + +Click the "Install to Engine" button and complete the installation. + +Congratulations! Initial setup is now complete. ๐ŸŽ‰ + + + +## Per Project Setup + +Each time you create a new Unreal Engine project in which you'd like to use the Ambit tools you will need to add the Ambit plugin to your project following the steps below. + +> โฑ Project setup takes about 5 minutes. + +Navigate to the Unreal Engine project to which you'd like to add Ambit. Inside that project folder create a "Plugins" folder (if it doesn't already exist.) + +`[MyUnrealProject]\Plugins\` + +Find the Ambit plugin folder that you downloaded during initial setup (or re-download if necessary.) Copy that folder to the "Plugins" directory you just created. + +`[MyUnrealProject]\Plugins\AwsAmbit\` + +Open your Unreal Engine project. + +In the Content Browser, click the 1 "View Options" button and enable the 2"Show Plugin Content" option. You should then see the 3 "Ambit Content" folder listed in the Sources pane. (You may need to toggle the ![Show Sources icon](images/setup/ShowHideSourcesIcon.png) icon to reveal the Sources pane.) + +![Content Browser view options](images/setup/ShowPluginContent.jpg) + +Congratulations! Your project is now ready to go. ๐ŸŽ‰ \ No newline at end of file diff --git a/docs/user-guide/docs-source/spawn-with-houdini.md b/docs/user-guide/docs-source/spawn-with-houdini.md index 6532dcd..c653e83 100644 --- a/docs/user-guide/docs-source/spawn-with-houdini.md +++ b/docs/user-guide/docs-source/spawn-with-houdini.md @@ -2,14 +2,7 @@ Ambit provides a tool to enable easy placement and randomization of your Houdini Obstacles. This tool is called **Spawn with Houdini** actor and operates very similarly to the [Spawn on Surface](/spawn-on-surface/) Ambit Spawner. -## Enable Houdini Engine for Unreal Engine 4 Plugin - -Make sure the [Houdini Engine for Unreal](https://www.sidefx.com/docs/unreal/_getting_started.html#GettingStarted_Install) plugin is installed and enabled in your Unreal Engine installation by going to **Edit** -> **Plugins** and ensuring the **enabled** checkbox for Houdini Engine for Unreal Engine 4 is checked. -**Note:** Only Houdini 18.5.696 or above is supported. The Houdini plugin you download should match the installed version of Houdini you have, as well as the Unreal Engine version. - -![Plugins Dropdown](./images/home/PluginDropdown.png) - -![Plugin Menu Houdini](./images/spawn-with-houdini/PluginsMenu.png) +> โš ๏ธ **Important:** This spawner type leverages the Houdini Engine. Be sure you have installed both the Houdini Engine and the Houdini plugin for Unreal before using this tool. See the [Setup](../setup) section of this user guide for instructions. ## Using Spawn with Houdini diff --git a/docs/user-guide/image-source/Images.key b/docs/user-guide/image-source/Images.key old mode 100644 new mode 100755 diff --git a/docs/user-guide/image-source/Images.pptx b/docs/user-guide/image-source/Images.pptx new file mode 100644 index 0000000..2e81797 Binary files /dev/null and b/docs/user-guide/image-source/Images.pptx differ diff --git a/docs/user-guide/image-source/Images_CityGeneration.pptx b/docs/user-guide/image-source/Images_CityGeneration.pptx new file mode 100644 index 0000000..d6adb29 Binary files /dev/null and b/docs/user-guide/image-source/Images_CityGeneration.pptx differ diff --git a/docs/user-guide/mkdocs.yml b/docs/user-guide/mkdocs.yml index 58e3aac..7744aad 100644 --- a/docs/user-guide/mkdocs.yml +++ b/docs/user-guide/mkdocs.yml @@ -1,22 +1,40 @@ docs_dir: docs-source site_name: AWS Ambit Scenario Designer for Unreal Engine 4 User Guide nav: - - Home: index.md - - Ambit Weather: weather.md - - Working with AWS in Ambit: aws-setup.md - - Individual Scenario Generation: individual-scenario-generation.md - - Bulk Scenario Generation: bulk-senario-generation.md - - Export Map Options: map-export.md - - Ambit Spawner Tools: + - Getting Started: + - Welcome: index.md + - Setup: setup.md + - Static Obstacles: - Overview: spawner-parent.md - Spawn on Surface: spawn-on-surface.md - Spawn in Volume: spawn-in-volume.md - Spawn with Houdini Digital Assets: spawn-with-houdini.md - Spawn on Path: spawn-on-path.md - Ambit Spawner Examples: spawner-examples.md - - Ambit Path Generation Tools: + - Dynamic Obstacles: - Overview: spawn-vehicle-path-parent.md - Spawn Vehicle Path: spawn-vehicle-path.md + - City Generation: + - Overview: city-generation.md + - Obtaining OpenStreetMap Files: obtaining-osm.md + - Building Generator: building-generator.md + - Road Generator: road-generator.md + - Weather & Time of Day FX: + - Overview: weather.md + - Simulation Scenarios: + - Manual Scenario Generation: individual-scenario-generation.md + - Automated Scenario Generation: bulk-senario-generation.md + - Working with AWS in Ambit: aws-setup.md + - Exporting Assets: + - Export Map Options: map-export.md + - APPENDIX: + - "Appendix: Contributing to Ambit Development": appendix-contributing.md + theme: readthedocs extra_css: - css/extra.css +markdown_extensions: + - toc: + baselevel: 1 + toc_depth: 2 + permalink: True