# Plug-in

Chameleon.tools plug-in is responsible for analyzing geometry in the Rhino scene to provide all the essential information urban planners and architects need. It automatically detects all the changes happening in the Rhino document, recalculates results for each individual object, aggregates these numbers, evaluates metrics, and presents the results in multiple panels.

## Evaluating Rhino objects
Each category of the imported project can be assigned with one of the document's layers. That way the plug-in knows what kind of objects to expect on given layer. How to assign layers will be described in [Settings panel](#settings-panel) section.

### Sectors
The plug-in supports dividing your design into multiple smaller sectors. All the results, as well as metrics, will be calculated for each of the existing sectors individually to give you more granular insights.

Sectors can only be non-overlapping **closed planar curves**.

### Areas
Objects placed on a layer that is assigned with `Area` category are expect to be represented by one of the following options:
- closed planar curve
- non-solid manifold brep or surface
- non-solid mesh

Computed `area` is the actual area of the rhino object (not an area of a projection).

### Buildings
For the objects placed on layers assigned to [simple category](/documentation/web-app#simple-categories) with object function of a `Building` type, or [mixed-use building](/documentation/web-app#mixed-use-buildings) category, allowed representations is:
- solid manifold brep
- solid closed mesh
- solid extrusion or surface

For such objects, the plug-in calculates its `floor-area` by horizontally slicing the objects on levels given by floor heights of assigned category and aggregating area of these shapes.

## Panels
All the panels the plug-in comes with can be individually open closed, moved around, or stacked like any other Rhino panel. Each of them offers a distinct set of functionalities that will be covered in the following sections.

Some of the panels show results for selected Rhino objects. Based on the current selection they will show results for:
- the whole project if no objects are selected
- selected sectors
- selected objects

If multiple sectors or objects are selected at the same time, results will be aggregated. In case you select sector(s) and regular object(s) at the same time, the plug-in will prioritize selected sectors and present their results.


## Settings panel

### Document settings tab
To start using the plug-in, you need to configure a couple of things:
1) One of your web-app [projects](/documentation/web-app#projects) needs to be imported
2) It's categories need to be assigned with Rhino layers
3) One layer for sector curves needs to be specified

And all these steps can be managed in *Document settings tab* which is divided into multiple collapsible sections.

#### Imported project
Displays information about currently imported projects.
When a project is imported, its current setting is saved to the Rhino document, and **subsequent changes of the project in the web app do not propagate to existing documents automatically but need to be manually synced**. This step ensures that the saved Rhino document will always work - even if the project gets deleted.

The section shows basic information and also the project's sync state. The possible states are:
- **In sync** - meaning that the project is up to date with the project in the web app.
- **Out of sync** - meaning that there are changes in the project that can be synchronized
- **Deleted** - meaning that the project was deleted in the web app - disabling the option to sync the project

The sync state is updated every time data is downloaded from the web app. That happens when:
 -  Rhino starts
 -  One of the following buttons is clicked
    -  **Sync project** in this section. This action will download fresh data and update the currently imported project. After clicking this action, the state should always be *In sync*
    -  **Refetch web-app data** located in [Plugin settings tab](#plug-in-settings-tab). This button only downloads the latest data so the project's state will be compared again

A project that is not in *Deleted* state can be edited in the web app. Simply click on `Edit Project` button. A new browser window should open on the project detail page where you can make any necessary changes. 
When you are done, don't forget to propagate changes back to the Rhino file using the `Sync project` button.

#### Layer Assignment
Any category from the imported project can be assigned with  a Rhino layer. On top of that, there should be one layer that will contain sector curves. This section displays all the categories defined in the currently imported project and the layer it's assigned with. 
> **Tip:** You can simply click on one of the listed category to select its layer

To change the assignment of the layers, you have two options: 
 - Automatic layer assignment that will create and assign all the layers needed for the currently imported project.
 - Manual layer assignment if you want to create layers on your own or reuse existing ones

### Plug-in settings tab

#### General
`Aggregate calculations by` controls how the plug-in aggregates the results. If the selected option is `category`, data is presented for each simple category separately. If the selected option is `function`, results for all the categories that are derived from a single object function will be added together so you will see results for every object function used in the design.
> Exported Excel file contains sheets for both views and will not be affected by this setting.

#### Visualization
Plug-in doesn't show calculated results only in panels but also directly in the rhino scene. It also uses various visualizations that help to easily navigate and identify possible issues. This section helps you control what is going to be displayed using the following toggles:

- `Show floors` - toggles visualization of building floors
- `Show errors` - toggles exclamation marks that appear above Rhino objects that the plug-in failed to process. The reason is either displayed above the object if *object info* is displayed, or in [Calculations panel](#calculations-panel) after selecting the object with error. 
- `Show object info` - toggles info panels appearing above Rhino objects containing calculated results for the given object
- `Visualization opacity` - changes the opacity of visualized building floors if they are displayed

#### Excel export
The plug-in can export all the calculated results to an Excel file to simplify further processing of the results.
If the `Export to Excel enabled` toggle is on plug-in will update an Excel file every time you save the Rhino document. You can find the document in the same location as the Rhino file you are working on - just the extension will be different (.xlsx)

The plug-in also offers interactive mode which means the Excel window is open and updated on-the-fly after every change. You can change the `Automatically open Excel` toggle to decide if an interactive Excel window should open automatically when Rhino launches. You can also check out the latest version of the file by clicking on the `Open Excel` button

> When Rhino is open, it is necessary to only open exported file through one of the plug-in's options as described above. Opening it directly (ie. by double-clicking it) prevents the plug-in from writing any changes.

#### Web-app
- `Refetch Web-app data` button - download the latest version of projects from the web app. It won't update the imported project of the currently opened Rhino document. To do so, click on the `Sync project` button in [Document settings tab](#document-settings-tab)
- `Open web-app data` button - opens Chameleon.tools web app in a new  browser window
- `Open documentation data` button - opens Chameleon.tools documentation in a new browser window

## Area analysis panel
Area analysis visually displays data related to calculated areas and floor areas of Rhino objects. Panel reacts to Rhino objects being selected. In case you want to observe the results of a specific sector(s) or object(s) for longer, you can use the `Lock view` button.

> The `Lock view` button does not prevent other objects from being selected in the Rhino scene. It only makes the panel 'remember' the current selection as long as you want. This button works globally for all reactive panels.

The panel also respects the value of the `Aggregate calculations by` control from [plug-in setting tab](#plug-in-settings-tab). If it is on, the results of categories with the same object function will be aggregated.

#### Space distribution
*Space distribution* section compares the aggregated floor area for each category/object function.

#### Land use
*Land use* section compares the area that is taken by each category/object function. The footprint of buildings is summed up as well. The bar chart shows the percentage of occupied area compared to the whole area of the project.

## Calculations panel
The calculations panel displays all calculated results for the whole project or selected sectors or objects. Panel reacts to Rhino objects being selected. In case you want to observe the results of a specific sector(s) or object(s) for longer, you can use the `Lock view` button.

> The `Lock view` button does not prevent other objects from being selected in the Rhino scene. It only makes the panel 'remember' the current selection as long as you want. This button works globally for all reactive panels.

The panel also respects the value of the `Aggregate calculations by` control from [plug-in setting tab](#plug-in-settings-tab). If it is on, the results of categories with the same object function will be aggregated.

The panel also allows you to manage settings specific to selected objects. 

#### Selected sectors setting

If one or more sectors are selected, a section called *Selected sectors setting* will appear. It allows you to set a custom name for any of the currently selected sectors. That is helpful when you need to quickly identify computed results - for example in [metrics tab](#metrics-panel) or [exported Excel](#excel-export) file.

## Metrics panel
The *metrics panel* presents results for [metrics](/documentation/web-app#metrics) defined in the web app. Their definitions are downloaded when the plug-in starts or after clicking on the `Refetch web-app data` button in the [plug-in settings tab](#plug-in-settings-tab). The plug-in evaluates metrics for the whole document and all the sectors individually.

The panel contains as many collapsible sections as there are enabled metrics for the current document. Each section displays results for one metric - each bar showing results for one sector in the document. On top of that, there is one *Total metrics results* section (the first one), that shows results for the whole document - one bar for one metric.

If a metric has a constant goal, it is possible to set its value - either for the whole project or for each existing sector. To do so, just click on the `Edit goals` button next to the given metric. It is also possible to hide metrics that are not relevant for the current document by clicking on the `Edit enabled metrics` button.

If the plug-in fails to calculate the value of the metric's result or its goal, or when the goal is not set at all, it will visually emphasize the faulty results.

Chameleon.tools

Get free trial