# Rhino
## Supported Rhino Versions
The plugin is compatible with the following software versions:
* **Rhino 7** — version **7.38.24338.17001** or later (available only via direct download from [food4rhino](https://www.food4rhino.com/en/app/cityweft))
* **Rhino 8** — version **8.21.25188.17001** or later
* **Grasshopper** (included with Rhino 7 and Rhino 8)
#### Supported Operating Systems
* **Windows**
* **macOS**
## Installing via Package Manager
1. **Open the Package Manager**
In Rhino, go to the **Tools** menu and select **Package Manager** (or type `PackageManager` in the Rhino command line).
2. **Search for “Cityweft” and install the plugin**
In the search bar, type **Cityweft** and press Enter. The Cityweft plugin will appear in the list of available packages.\
Click on the Cityweft package entry, then press Install. Rhino will automatically download and install the latest compatible version.
3. **Restart Rhino**
Once the installation is complete, **restart Rhino** to ensure the plugin loads correctly.
4. **Verify Installation**
After restarting, open the **Plugins** tab in Rhino or Grasshopper to confirm that **Cityweft** appears in the list of installed plugins.
5. When you open the Cityweft Plugin, the container will open, and you're ready to go!
## Activating Plugin
A **valid Cityweft API key** is required to use the plugin.
You must have an **active subscription or bundle package** that includes API access in order to retrieve an API key.
API keys can be generated and managed from your **Cityweft API Dashboard**.
For detailed instructions on how to obtain and manage your API key, see the section:
{% content-ref url="getting-your-api-key" %}
[getting-your-api-key](https://cityweft.gitbook.io/docs/plugins/getting-your-api-key)
{% endcontent-ref %}
## **Getting Started**
Before getting started, ensure you have followed the instructions for both installation and API key access.
### 🔑 **Activating your API Key**
To activate the plugin the first time, you need to enter your API key. If you do not have this, please visit the **‘Getting your API Key’** page
1. Once you have retrieved your API key, simply go to the usage tab and find the ‘Set API Key’ button\
2. Simply paste your API Key into the field, and press ‘OK’
3. Once input correctly, you are ready to go!
### 🏢 **Getting Your Model**
1. In the Cityweft window, **navigate or search** for your desired site location.\
2. **Select an area** on the map using the polygon selection tool.
3. **Choose your save folder in the output settings**
Before downloading, open the **Output Settings** section:
* **Filename:** Enter the name you’d like for your model file (e.g., `Paris`).
* **Output Folder:** Choose where you’d like the model files to be saved on your computer.
All generated files will be placed in this folder.
> 💡 Tip: Create a dedicated folder for each project area to keep your Cityweft models organized.
4. **Press the ‘Download and Import Model’ button**\
\
The model will automatically appear in the viewport\
If you are selecting a large area with dense geometry, this process can take up to 1-2 minutes.
5. **View all the model layers in the layer manager**
6. Geometry metadata
* In addition to geometry, the model contents also contain a host of metadata, including building name, facade material, and more
* To view this information, simply click on any object and open the **Attribute User Text** under **Properties**\
### ⚙️ Plugin **Settings Overview**
The Cityweft Rhino plugin includes several settings that control what data is included and how it is processed when generating models.
These are grouped into three main categories:
***
#### **1. Geometry Types**
*(Check boxes — choose which layers to include in your model)*
These options let you define which geometry types to include when downloading the model.
| **Option** | **Description** |
| ------------------ | ---------------------------------------------------------------------- |
| **Buildings** | Imports buildings and roof geometry. |
| **Surface** | Includes ground surfaces such roads, green space, or base mesh. |
| **Barriers** | Adds physical boundaries like fences, retaining walls, or embankments. |
| **Topography** | Imports detailed elevation data and terrain contours. |
| **Infrastructure** | Adds infrastructure layers such as trees, bus stops, or benches |
> 💡 Tip: If you only need building geometry, uncheck other layers to speed up processing.
***
#### **2. Processing Options**
*(Check boxes — controls how geometry is handled during conversion)*
| **Option** | **Description** |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Force flat surface** | Deactivates surface geometry projection onto Topography. When Topography is activated, this will generate all surfaces (roads, parks, water) at z=0, while topography layer is generated seperately. |
***
#### **3. Building Settings**
*(Adjustable fields — define defaults for missing data)*
| **Setting** | **Description** |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Default Roof Type** | Sets a default roof geometry type for buildings that lack roof data. This does **not** override existing roof shape information. |
| **Default Levels** | Specifies how many building levels to assign when no height data is available. |
| **Default Level Height (m)** | Defines the assumed height of each building level in meters. Used to estimate total building height when no data exists. |
> 🏗️ These settings ensure that all buildings generate correctly, even when data is incomplete.
