# Web app

The main purpose of the Chameleon.tools web application is to allow you to easily define reusable project definitions and share them with your team. The project is a set of information the plug-in needs to determine what is going to be calculated and how.

The application is closely integrated with [Rhino accounts](https://accounts.rhino3d.com/?controller=home). That means that after logging in, you will be able to switch between accounts to work under either your personal account or one of the teams you are part of. Being part of a team allows you to share projects and all the relevant settings with your coworkers - minimizing the overall time needed to set up the plug-in for your specific use cases.

Following chapters will describe all the building blocks and other necessities that are needed to define a project.

## Object functions

Object function is an abstract representation of objects that have the same purpose. It can be for example:
- Residential building
- Greenery area
- At-ground parking area
- Garage building

Each of these functions will have its own set of calculations that are going to be evaluated for every Rhino object falling under the same category. 

### Defining object functions
When creating or updating an object function, you can update any of the following properties:
- **Name** - function's name
- **Identifier** unique identifier to help help you reference specific object functions while defining [metrics](#metrics)
- **Description** - optional description
- **Color** - a color that can help you distinguish objects of different object functions on the Rhino scene
- **Function type** - a dimension of Rhino object that is relevant for a given object function. It can be either `area` or a `building`.
- **Default floor height** - for object functions of a type `building`, you will have a chance to set the default height for each floor. This value is needed for evaluating calculations of 3D Rhino objects correctly. Value is optional.
> To avoid possible conflicts in naming, `SECTOR` and `BUILDINGS` are reserved identifiers that cannot be used when defining an object function.

Once the object function is created, you will be redirected to its details, where you can define its variables and calculations.

#### Variables
Every variable is a building block needed 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 according to the actual size of the Rhino object.

Each user-defined variable is defined by the following properties:
- **Name** - variable's name
- **Identifier** - a unique variable identifier that will help you reference the actual value in the [calculation's](#calculations) expression.
- **Description** - optional description
- **Default value** - optional default value of given variable
> To avoid possible conflicts in naming, `area` and `floor_area` are reserved identifiers that cannot be used when defining a variable.

#### Calculations
It is possible to define as many calculations for each object function as necessary. Each of these calculations represents a value that is going to be computed for each object later on in Rhino. To give an example, let's imagine a typical residential building. For such object function, possible calculations might include:
- Number of apartments
- Number of tenants
- Parking spots needed

Each calculation is defined by the following properties:
- **Name** - variable's name
- **Identifier** - a unique identifier that will help you reference the actual calculation result while defining [metrics](#metrics)
- **Description** - optional description
- **Expression** - optional default value of a given variable
> To avoid possible conflicts in naming, `area` and `floor_area` are reserved identifiers that cannot be used when defining a calculation.

### Concept of categories
A single object function is not enough to cover all possible scenarios your project might need. The average area a single person occupies is different in the city center and in the country. To be able to accurately reflect both of these examples (and many more), it is possible to derive multiple categories from each object function. For each of these categories, you will need to input values for every user-defined variable. That is why all the calculation expressions should be written in a generic way allowing you to adapt to different scenarios.

Categories are declared on the [project detail](#projects) page to reflect different statistical values for each district, city, or country.

## Metrics
Metrics provide a  way how to keep important metrics of the project under control. As opposed to object functions' calculations, which are calculated for each Rhino object independently, metrics allow you to work on a higher level and have access to aggregated results of object functions. That can become handy if you want to make sure that: 
- Floor area ratio (FAR) is below the local limit
- Building Coverage Ratio (BCR) is below the local limit
- The number of parking spots available meets the demand
- and more

To help you identify possible issues as soon as possible, it is possible to define a goal for each metric. If the plug-in detects that the calculated value doesn't meet the goal, you will be visually notified on [Metrics panel](/documentation/plug-in/#metrics-panel). The results of metrics are calculated for the whole project and also for each of the [sectors](/documentation/plug-in/#sectors) separately. Goals can also be set globally or overridden for any of the sectors that exist in the design.

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

#### Expression
The value of each metric is calculated using a mathematical expression. In this case, variables represent aggregated results for each object function and their calculation. To access the value, just use the identifier in the following format: `<OBJECT_FUNCTION_IDENTIFIER>.<calculation_identifier>`, where `<OBJECT_FUNCTION_IDENTIFIER>` is an identifier of one of the selected object function, and `<calculation_identifier>` is an identifier of one of this function's calculation.

There is also a set of additional variables that is possible to use when declaring the expression:
- `SECTOR.area` - area of given sector
- `BUILDINGS.area` - aggregated footprint area of all buildings
- `BUILDINGS.floor_area` - aggregated floor area of all buildings

#### Goal type
Possible options for the type of metric's goal:
- **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 also possible to enter the default value for the goal. Its value can be later overridden in the plug-in either for the whole project or for specific sectors to allow you to uphold the local regulatory framework.
- **Calculated** - for goals where both sides of the equation are calculated based on the actual geometry in the Rhino file. 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 parking spots. 
If this section is selected, it is necessary to also input expression for calculating the goal.
- **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*.

## Projects
Each project consists of multiple categories. Once the project is imported to Rhino, each of its categories can be assigned with one of the layers - effectively linking together the definition created in the web app with the geometry in the Rhino file. Thanks to this connection, the plug-in will know how to evaluate objects, what properties to calculate, and how.

### Simple categories
A simple category is a specific instance of one of the object functions. When you want to add one, you will need to give it a name, select one of the existing object functions, and fill in the values of all 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 each object](/documentation/plug-in/#evaluating-rhino-objects) correctly.

You can create as many simple categories in each project as you wish to cover all use-cases you have and multiple categories can derive from the same object function.

### Mixed-use buildings
Mixed-use building categories cover situations when some of the buildings in your design do not have a single purpose - which can be quite often.
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:
- simple category of `building` type
- number of floors in the section
- height of each floor (if the value is not set, the floor height of the linked category will be used)

Because the height of the actual objects in the Rhino document can vary, there is exactly one section without a specified number of floors.
**This composition item will stretch to fill available space**.


To learn about the Rhino plug-in, continue to [plug-in documentation](/documentation/plug-in).

Chameleon.tools

Get free trial