# Web app

The Chameleon.tools web application enables you to define reusable project configurations and share them with your team. A project is a set of information the plug-in needs to know how to analyze the geometry existing in the Rhino file.

## Account
You can sign up for the web application using your  [Rhino account](https://accounts.rhino3d.com/?controller=home). After logging in, you can switch between your personal account and any teams you belong to.

<div style="max-width: 300px;">
  <img src="/documentation/web-app/account-select.png" alt="Account select">
</div>

:::info
Each account is created together with an example project that can be used to test things out. 
:::

## How it works

There are a couple of building blocks that allow you to compose a project that can be later on used by the plug-in to know how to process the geometry.

### Object functions

An object function is an abstract representation of objects with a specific purpose. For example:

- Residential buildings
- Green space
- Ground parking
- Parking garage

For each object function, you can define what is going to be calculated and how. In case of residential buildings, you might want to calculate the number of apartments, the estimated number of tenants, gross revenue from selling the building, or any other metric relevant for your use-case.

Object functions can be defined using variables, making them flexible enough to cover various use cases. A single definition can be reused multiple times within the same project or across different projects.

<div style="max-width: 600px;">
  <img src="/documentation/web-app/object_function_category.png" alt="Web-app building blocks">
</div>


#### Basic properties

- **Name** of an object function will be used in both the web-app and the rhino plug-in.

- **Identifier \*** is a parameter that needs to be unique for each object function. It can be used to reference specific object function when defining [metrics](#metrics)

- **Description** can help you further describe the purpose of given object function. The value is optional.

- **Color** will be used to help you distinguish objects of different object functions apart in Rhino scene.

- **Function type** can be either `Area` or `Building`. The plug-in will only evaluate objects that are relevant for given function type.

- **Default floor height** can be optionally specified for object functions of a type `Building`. Rhino plug-in will use this value to correctly evaluate 3D geometry objects in Rhino scene.

:::warning
\* To avoid reference conflicts, `SECTORS` and `BUILDINGS` are reserved identifiers that cannot be used.
:::

#### Variables
Variables can be used to put together a working mathematical expression that should be generic enough to cover all possible use-cases. 
There is always one variable available by default - **`area`** for object functions of type `Area`, and **`floor_area`** for object functions of type `Building`. This variable is calculated by the plug-in based on the actual dimensions of the Rhino geometry object.

Each user-defined variable consists of following properties:
- **Identifier \*** is a parameter that needs to be  unique for every variable of given object function. It is used to reference the actual variable value when defining mathematical expression of [calculation](#calculations).
- **Description** can be used to further describe purpose of given variable
- **Default value** value of user-defined variables is set when creating project's categories. If no value is set there, the default value will be used.

:::warning
\* To avoid reference conflicts, `area` and `floor_area` are reserved identifiers that cannot be used.
:::

#### Calculations
Calculations define what is the Rhino plug-in is going to calculate for each geometry objects falling under the given object function. For each calculation, the plug-in calculates a result based on its dimensions and values of other user-defined variables.

<div style="max-width: 800px;">
  <img src="/documentation/web-app/variables.png" alt="Web-app building blocks">
</div>


The main part of the calculation is its expression, where you can use identifiers of [variables](#variables) to reference their value.

<div style="max-width: 600px;">
  <img src="/documentation/web-app/object_function_referencing.png" alt="Web-app building blocks">
</div>

> The example expression above ☝️ uses value of default `floor_area` variable calculated by the plug-in, and two user-defined variables (`avg_apartment_area` and `avg_tenants_per_apartment`) whose value is going to be set for each [category](#single-purpose-categories) deriving from given object function.

There is always one calculation by default - **`area`** for object functions of type `Area`, and **`floor_area`** for object functions of type `Building`.

Each calculation consists of following properties:
- **Name** of calculation is going to be used in Rhino plug-in to present calculated results
- **Identifier \*** is a parameter that needs to be unique for each calculation in given object function. It can be used to reference specific calculation result when defining [metrics](#metrics)
- **Description** can be used to further describe purpose of given calculation
- **Expression** is a mathematical expression that tells the plug-in how to calculate result for given calculation.

:::warning
\* To avoid reference conflicts, `area` and `floor_area` are reserved identifiers that cannot be used.
:::

### Projects
A project links the web application to the plugin. After opening a new Rhino file, importing one of your projects is a necessary step to give the plug-in all the information it needs to analyze geometry.

A project contains a set of categories that can be either single-purpose categories or multi-purpose buildings. Once the project is imported to Rhino, each of its categories can be assigned with one Rhino layer - effectively linking together the definition created in the web-app with the geometry in the Rhino file. This way, the plug-in as able to tell different objects apart and calculate relevant results.

<div style="max-width: 600px;">
  <img src="/documentation/web-app/web-app-overview.png" alt="Web-app building blocks">
</div>

#### Single-purpose categories
A single-purpose category is a specific instance of one of the [object functions](#object-functions).
To create a single-purpose category, you will need to chose a name, select one of the existing object functions, and fill in values of its user-defined variables. If the selected object function is of a type `building`, you will also have to set floor height so the plug-in can [evaluate](/documentation/plug-in/#evaluating-rhino-objects) 3D objects correctly.

#### Multi-purpose buildings
Multi-purpose buildings come into play if a single-purpose category is not enough to properly represent a set of buildings in your design. 
They are composed from single-purpose categories of given project. For example, a building might have a two-story underground garage, commercial spaces on the first floor, and apartments above.

<div style="max-width: 700px;">
  <img src="/documentation/web-app/composition.png" alt="Web-app building blocks">
</div>

To create such a category, you will need to define building composition where each section represents a number of consecutive floors of the same category from the bottom to the top. Each of these composition items is defined by:
- category - can be choses from all single-purpose categories of a type `Building` that exist in the given project
- floors count in the section. One section does not have to have the number of floors defined. This section will **fill all the available space**.
- flor height of each floor (if the value is not set, the floor height of the linked category will be used)


### Metrics
Metrics provide a way how to keep important aspects of your design under control. Setting up a metric can help you in case you need to make sure that:
- floor area ratio (FAR) is below the local regulatory limit
- building Coverage Ratio (BCR) is below the local regulatory limit
- the design meets demand for car parking spaces

Metrics are calculated for the entire design, but also for each of its [sectors](/documentation/plug-in#sectors) to provide more insights. 

Besides metric's **name**, **description** and **color**, you can edit following properties:

#### Expression
The value of a metric is calculated by evaluating a mathematical expression that can reference aggregated results of any [calculation](#calculations) defined as part of any object function. To access the aggregated value, use the identifier in the following format `<OBJECT_FUNCTION_IDENTIFIER>.<calculation_identifier>`.

<div style="max-width: 800px;">
  <img src="/documentation/web-app/metrics_variables.png" alt="Web-app building blocks">
</div>

There are also three special variables that can be used
- `SECTOR.area` - area of given sector (or all sectors when metric is calculated for entire design)
- `BUILDINGS.area` - aggregated footprint area of all buildings in given sector (or all buildings when metric is calculated for the entire design)
- `BUILDINGS.floor_area` - aggregated floor area of all buildings in given sector (or all buildings when metric is calculated for the entire design)

#### Goal type
To know whether the metric meets the desired criteria, it is possible to define a goal. Possible options for the type of metric's goal are:
- **Constant** - for metrics that have constant goals like (FAR or BCR), where a single value will determine whether the goal is met or not. If this option is selected, it is possible to fill in default value of the goal. If specific design needs to uphold different standards, it is always possible to edit the value in the plug-in on [Metrics panel](/documentation/plug-in/#metrics-panel). On this panel, you can specify a goal for the whole project, but it is also possible to fill in different values for each of the existing sectors.

- **Calculated** - for goals where both sides of the equation are calculated based on the actual geometry in the design. It comes in handy for calculating parking spot demand and other similar metrics. The number of cars residing in a given area can be calculated as same as the number of available parking spots. 
If this section is selected, it is necessary to input expression for calculating the goal. The same set of variables can be used as for defining the metric's expression.
- **None** - for metrics where no specific goal is targeted

#### Goal criteria
This option will tell the plug-in whether the value of the metric is supposed to be higher or lower than its goal. This option is available only if the goal type is either *constant* or *calculated*.


Chameleon.tools

Get free trial

Getting started

Plug-in