# Plug-in

The Chameleon.tools plug-in analyzes geometry in Rhino to provide essential data for urban planners and architects. It automatically detects changes in the Rhino document, recalculates data for affected objects, aggregates results, evaluates metrics, and presents final results in multiple ways.

The plug-in is designed to seamlessly integrate into the Rhino workflow, enabling users to visualize and evaluate urban designs in real-time.

## Setting up a new design

In order to make the plug-in work, there are two steps necessary:
- Import one of the projects defined in the [web-app](/documentation/web-app)
- Assign Rhino layers with project's categories.

You will be automatically prompted to do both task at once every time you open a Rhino document without imported project. You can also always do both things in the [Settings panel](#settings-panel).

## How it works

The plug-in evaluates each object individually based on its actual dimensions and the category it represents. For each Rhino document, there is always one imported [project](/documentation/web-app#projects), which determines the available categories for the design.

The plug-in builds on top od Rhino's layer system. Each category from the imported project can be assigned with one Rhino layer. This allows the plug-in to identify objects and process them accordingly. The plug-in continuously monitors changes in the Rhino document, ensuring that calculations remain up to date.

<div style="max-width: 900px;">
  <img src="/documentation/plug_in/layers_categories.png" alt="Web-app building blocks">
</div>

There are three kinds of objects the plug-in recognizes:

### Buildings
If object's layer is assigned with `Building` type [single-purpose category](/documentation/web-app#simple-categories), or [mixed-use building](/documentation/web-app#mixed-use-buildings) category, the plug-in expect an object with volume. The possible representations are:
- solid manifold brep
- solid closed mesh
- solid extrusion or surface

For such objects, the plug-in calculates `floor-area` variable value by horizontally slicing the objects on levels given by floor heights and summing up areas of these shapes.

### 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` variable value is the actual area of the rhino object (not an area of a projection).

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

Sectors can only be **closed planar curves** that should not overlap.

:::info
All analyzed objects should always be inside a sector for all calculations to work correctly.
:::

## Control Panels
The plug-in provides four control panels where you can access all settings and results. These panels can be opened, closed, moved, or stacked like any other Rhino panel. Each serves a distinct purpose and offers specific functionalities.

The panels are interactive and update dynamically based on object selection in the Rhino scene. Depending on the selection, they will display results for:
- The entire project if no objects are selected
- Selected sectors if one or more sectors are selected
- Selected objects if individual objects are selected


### Settings panel - Document settings tab

#### Imported project

A project contains all definitions that are needed for evaluating the design. When a project is successfully imported, its configuration is saved to the Rhino document and **all further synchronizations need to be done manually.** That means that subsequent changes of the project made in the web app do not propagate to existing documents automatically.

:::info
Because the project's setting is saved locally, even deleting the project in the web-app will not make the plug-in stop working.
:::

The section displays information about the currently imported project, including its sync state. The possible states are:
  - **In sync** - the project is up to date with the project in the web-app.
  - **Out of sync** - the local project configuration differs from the one that is saved in the cloud, because there were some changes made
  - **Deleted** - the project was deleted in the web-app. The option to sync the project or edit it should be disabled

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` button located in this section. This action will download fresh data and update the currently imported project. After clicking on this button, the state should always be *In sync*
    -  `Refetch web-app data` button located in [Plugin settings tab](#settings-panel---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 editing the project, 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 one Rhino layer. On top of that, there should be one layer for sector curves. This section displays all the categories defined in the currently imported project and the layer it's assigned with.

:::info
You can simply click on one of the listed category to select its layer
:::

To change the assignment click on the `Assign layers` button. It has two options: 
 - Automatic layer assignment will create a structure of layers for the currently imported project and assign them with its categories.
 - Manual layer assignment can be used to use manually assign categories with existing layers.

### Settings panel - 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 single-purpose 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.
:::info
Exported Excel file contains sheets for both views and will not be affected by this setting.
:::

#### Visualization
The plug-in doesn't show calculated results only in panels but also directly in the Rhino scene. It offers various visualizations providing quick feedback loop. 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.

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

:::warning
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 to the file.
:::

#### 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](#settings-panel---document-settings-tab)
- `Open web-app data` button - opens Chameleon.tools web-app in a new browser window
- `Open documentation` button - opens Chameleon.tools documentation in a new browser window

### Area analysis panel
The Area Analysis panel visually displays aggregated data for calculated areas and floor areas of Rhino objects. It updates dynamically based on selected objects. To focus on a specific part of the project (e.g., a sector) while making changes, use the `Lock view` button. This locks the panel to the current selection at the moment the button is pressed.

:::info
The `Lock view` button works globally for all panels offering same functionality.
:::

#### Space distribution
*Space distribution* section compares the aggregated floor area for each `Building` 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 that given category/object occupies.

:::warning
Bar chart computes the occupied area by comparing the value against area of the sectors the objects are part of. For the chart to work correctly, all object should be placed in a sector.
:::

### Calculations panel
The calculations panel displays all calculated results in numeric format, and provides a ways to manage settings specific to selected objects. It updates dynamically based on selected objects. To focus on a specific part of the project (e.g., a sector) while making changes, use the `Lock view` button. This locks the panel to the current selection at the moment the button is pressed.

:::info
The `Lock view` button works globally for all panels offering same functionality.
:::

#### Selected sectors setting
If one or more sectors are selected, a section called *Selected sectors setting* will appear. It allows to set a custom name for any of the currently selected sectors. That is helpful easy identification of 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](#settings-panel---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. And each bar shows results for one sector in the document. On top of that, the first section called *Total metrics results* shows results for the whole document - one bar for one metric.

If a metric has a goal, it can be either calculated goal or constant goal. If a metric has a constant goal, it is possible to set its value either for the whole project or individually 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 design 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