Skip to content

Commit

Permalink
Expand and organize User Guide (#3)
Browse files Browse the repository at this point in the history 
* Expand and organize User Guide.

- Added documentation for City Generation tools.
- Migrated setup instructions from README to User Guide.
- Improved setup instructions.
- Improved TOC.
  • Loading branch information
@kris-work
kris-work authored Dec 2, 2021
1 parent da1cd42 commit 7f8e768
Show file tree
Hide file tree
Showing 37 changed files with 339 additions and 201 deletions.
168 changes: 15 additions & 153 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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: <https://www.sidefx.com/docs/unreal/_getting_started.html>.

#### 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 `<AmbitPluginRoot>/HoudiniDigitalAssets/AWSAmbit.hda` into the special user-specific Houdini OTL directory. On Windows you'll find this directory at `C:\Users\<username>\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\<username>\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 |
Binary file added docs/readme-images/AmbitBanner.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
108 changes: 108 additions & 0 deletions docs/user-guide/docs-source/appendix-contributing.md
View file
Original file line number Diff line number Diff line change
@@ -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...

`<your sample project>\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".
8 changes: 4 additions & 4 deletions docs/user-guide/docs-source/aws-setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
16 changes: 16 additions & 0 deletions docs/user-guide/docs-source/building-generator.md
View file
Original file line number Diff line number Diff line change
@@ -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.

Loading

0 comments on commit 7f8e768

Please sign in to comment.