Skip to content

Developer Guide

Jump to bottom
Juney Lee edited this page Nov 9, 2024 · 17 revisions

This guide contains instructions to help you get started with the development of COMPAS RhinoVAULT.

Requirements

1. Clone COMPAS RhinoVAULT Repository

Clone the repository of COMPAS RhinoVAULT using Git or a Git GUI.

git clone https://github.com/BlockResearchGroup/compas-RV.git

The repo contains the following directories

  • data -- sample data for testing.
  • gitbook -- source code for the documentation gitbook.
  • plugin -- command scripts and project definition
  • resources -- general package resources such as illustrator files
  • src -- source code of compas_rv

Note

Note that the functionalities of compas_rv is not meaningful outside the context of this plugin in Rhino 8. It is therefore not released on PyPI, and it is not listed as one of the requirements in requirements.txt. It is included as a plugin "Library" and can be used in all command scripts without explicit installation.

2. Dev environment

Create a development environment, and install all "dev" requirements.

conda create -n rv-dev python=3.9 -y
conda activate rv-dev
cd compas-RV
python -m pip install -e ".[dev]"

Warning

This environment is independent of Rhino. It does not replace the steps described in the next section. it is useful for working in parallel with VS Code outside of Rhino, and for making "editable installs" as described later.

3. Rhino Setup

The Rhino commands of COMPAS RhinoVAULT define their requirements at the top of each command script using the Rhino "requirements comment" syntax (# r: ...). If these requirements are not already available in Rhino, they will be installed automatically in an environment called rhinovault.

#! python3
# venv: rhinovault
# r: compas>=2.5, compas_rui>=0.3.1, compas_session>=0.4.1, compas_tna>=0.5

If you want to modify a command in a way that requires additional packages, or different versions of packages, you should make the corresponding changes in those comments.

Editable Installs

Note that you can manually overwrite the command requirements with editable installs from local source, using pip with as a --target the Rhino rhinovault environment. Do this for for any package that you want to modify and use locally.

Rhino automatically adds a unique suffix to the name of "site-envs". Here it is WCnHZgZr resulting in rhinovault-WCnHZgZr instead of just rhinovault. This suffix might be different on your machine. Navigate to %USERPROFILE%\.rhinocode\py39-rh8\site-envs to find the path to this Rhino environment.

Navigate to the folder of the local repository (e.g. compas):

cd compas

Upgrade pip (you only have to do this once):

%USERPROFILE%\.rhinocode\py39-rh8\python -m pip install --upgrade pip

Install package to the Rhino's rhinovault environment:

python -m pip install . --upgrade --no-deps --target %USERPROFILE%\.rhinocode\py39-rh8\site-envs\rhinovault-WCnHZgZr

Note that you can use the python executable of your conda environment rv-dev instead of the executable of Rhino, as long as you use the correct target (and have python3.9 in rv-dev as well).

Note

For Mac, the path names and forward/back slashes may need to be adjusted accordingly.

4. Working with Rhino project files (*.rhproj)

The plugin project is defined in plugin/RhinoVAULT.rhproj. This is a JSON file with a special extension (*.rhproj) containing all project settings. The contents of the file can be modified using Rhino Script Editor.

To open the editor, type ScriptEditor in the Rhino command line. Then open the project with File > Open Project.

RV_project

You can add new commands, embed libraries, or add shared resources. Whenever you make changes, the project has to be rebuilt, and you have to restart Rhino before the changes have effect.

RV_publish-project

Detailed information about Rhino Plugin Projects can be found here.

5. Making edits to commands

The items listed under Commands in the project browser are command names and provide only "views" of the corresponding source code. These views cannot be modified directly. In order to modify the actual commands, you will need to open each of the individual scripts, or the plugin folder.

You can modify the scripts directly using the Script Editor in Rhino, or use VS Code outside of Rhino. Any saves made outside of Rhino will be updated instantly in the Script Editor.

Clone this wiki locally