Getting started with your own project

Since the City Energy Analyst (CEA) tool requires a strict folder structure for input files to work with its scripts, it can be difficult and troublesome to create and start a new project.

To help our users get started with CEA, we have created tools that would help set up the required input files and databases in the right structure, so that you guys can get started on the analysis and simulations as soon as possible!

Currently, we have 2 ways to help create a project, the create_new_project tool and our newly created dashboard tool, which is more user-friendly and provides users with a graphical interface.

We want to make creating a new project as easy as possible, that is why we have created a new Dashboard tool that launches in your web browser.

Starting a new project

The most basic folder structure for a new project looks like this:

New_Project
    ├───Scenario_A
    │   └───inputs
    │       ├───building-geometry
    │       │    └─── //Zone geometry files...
    │       │    └─── //District geometry files...
    │       ├───networks
    │       │   └─── //Street geometry files...
    │       └───topography
    │           └─── //Terrain file...
    └───Scenario_B
        └─── ...

Every project is a folder that consists of multiple scenarios, each having their own input files.

There is a minimum set of inputs that you need to prepare to run scripts for a new project,

District geometry file: A shapefile storing the geometry of buildings and surroundings.
Zone geometry file: A shapefile storing the geometry of buildings.
Streets geometry file: A shapefile storing streets and pathways
Terrain file: Digital elevation model of the terrain.

The Zone file follow a structure that can found here.

Below we will show you how to use the dashboard tool to help bootstrap and create the required files and folders so that you can get started on a new project.

Using our new Dashboard tool

If you have already installed CEA with our installer, you can start the dashboard tool using the CEA Dashboard shortcut.

If not, you can get it here.

Instructions regarding installation can be found in our other blog post.

1. Creating a new project

Upon launching the dashboard tool, you will be greeted with a landing page in your browser.

Select Create new project, enter a name for the project and select a location where you want to save it.

Click Create and you will be brought to the Project Overview page.

2. Creating a new scenario

From the Project Overview page, select Create new scenario to create a new scenario for your project. Enter a name for the scenario.

There are two ways you can add input files to the scenario, generate them with our Data Management Tools or import them using files that you might already have. For this post, we will demonstrate how to create the required input files using our data tools.

3. Creating input files for scenario

To help generate input files for a new scenario, we have created four data tools,

zone-helpe
district-helper
streets-helper
terrain-helper

Our data tools try to pull crowd-sourced data from OpenStreetMaps to create the new input files. These tools are available on both our command line and dashboard interface.

More information regarding our data tools can be found in our blog series here.

Select the checkbox of the respective tools that you want to use.

You will be able to configure the parameters of each data tool by clicking the gear icon next to their name.

2b. Creating Zone geometry files

To use our zone-helper tool, you will need to have a site geometry file which contains a polygon that encloses buildings in your area of interest. Fortunately, our dashboard has a map that allows you to indicate the buildings you want and create the site file for you.

You can navigate the map to the area of interest by searching for the name of the location or its coordinates(latitude, longitude).

In this case, we will be selecting a few buildings in Singapore.

Once you have found the buildings that you want, click on points around the buildings to select the area where you want the zone-helper to generate building geometries for you. Buildings within the red polygon will be generated.

Click Create and the program will run all the data tools that you have selected. This might take some time, depending on the size of the area you have selected and the number of data tools that need to be run.

After all the data tools have finished running, you will be brought to the Inputs page.

3. Editing input files

The Inputs page is where you will be able to view or edit the input files that you have just generated.

To edit a input file, select the type of input that you want to edit on the left.

In this case, we will be changing the height of one of our district buildings.

Click on the building you want to edit in the table below.

A form for the building with its properties will pop up. Edit the properties to want you want and click OK. You can continue editing any other building for this input.

Do note that these changes are only temporary and will only be saved after you have pressed the Save button. You can also discard any unsaved changes by clicking the Discard button.

4. Start running simulations!

And that's it! You are now ready to start running simulations based on the input files that you have just generated.

** For some of the scripts, we would require more information regarding the properties of the buildings. For this, you can run our data-helper tool to generate these properties based on our databases and you will be good to go!

More information regarding data-helper can be found in our blog series here.