Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add install docs page #35

Merged
merged 6 commits into from
May 7, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
File renamed without changes.
16 changes: 11 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# AI-eXtended Design (AIXD): Grasshopper plugin
# ARA: AIXD Grasshopper plugin

Grasshopper plugin for the AIXD toolkit.

Expand All @@ -11,24 +11,30 @@ Grasshopper plugin for the AIXD toolkit.
- flask

#### Latest stable version

Install `aixd_ara` using `pip`
```
```bash
pip install aixd_ara
```

Install `aixd_ara` using `conda`:
```
```bash
conda install -c conda-forge aixd_ara
```

Install the plugin in Rhino/Grasshopper using the following command:
```bash
python -m compas_rhino.install -v 7.0
```

**Note**: It is recommended to use virtual environments to manage the dependencies of your projects. If you are using
`conda`, you can create a new environment with `conda create -n myproject python=3.9` and then activate it with
`conda activate myproject` before installing `aixd_ara`.

#### Latest unstable version

Install the latest version using `pip` from the git repository:
```
```bash
pip install --upgrade git+https://github.com/gramaziokohler/aixd_ara.git
```

Expand All @@ -41,7 +47,7 @@ git clone https://github.com/gramaziokohler/aixd_ara.git
cd aixd_ara
```

Then, install using conda, to install all the dependencies into a new environment called `aixd_gh`:
Then, use conda to install all the dependencies into a new environment called `aixd_ara`:
```bash
conda env create -f environment.yml
```
Expand Down
117 changes: 117 additions & 0 deletions docs/installation.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,120 @@
********************************************************************************
Installation
********************************************************************************

This page provides a guide for installing the ``ARA`` plugin on your system.
The plugin can be installed using an installer, or a package manager for Python such as ``pip`` or ``conda``.

The following instructions will guide you through each method.
Alternatively, you can clone the ``aixd_ara`` source code directly from
our `repository <https://github.com/gramaziokohler/aixd_ara>`_.

Installer
=========

The installer is the easiest way to install the plugin on your system
for the majority of users.

Windows Users
-------------

* Download `the ZIP file <https://github.com/gramaziokohler/aixd_ara/raw/main/install.zip>`_.
* Extract it to any folder of your preference.
* Double-click the `install.cmd` file to start the installation.

Mac Users
---------

On Mac, it's not necessary to download the installer. Instead,
open the Terminal application of your mac, copy & paste the following
command, and press Enter:

.. code-block:: bash

curl -s https://github.com/gramaziokohler/aixd_ara/raw/main/install.bash | bash


Installation using pip
======================

The most popular package manager for Python is ``pip``.
You can use it to install packages from the Python Package Index and other indexes.

**Step 1: Update pip**

It is good practice to ensure that you are using the latest version of ``pip``.
To update ``pip``, run the following command:


.. code-block:: bash

python -m pip install --upgrade pip

**Step 2: Install plugin**

To install `ara_aixd` using ``pip``, execute the following command:

.. code-block:: bash

pip install ara_aixd

And then install the plugin in Rhino/Grasshopper using the following command:

.. code-block:: bash

python -m compas_rhino.install -v 7.0


Installation using conda
========================

``conda`` is an open-source package management system and environment
management system that runs on Windows, macOS, and Linux.
It’s very popular in the realm of scientific computing.

**Step 1: Create a conda environment (Optional)**

It's often beneficial to create a new environment for your project. This can be done using the following command:

.. code-block:: bash

conda create --name project_name python=3.x


Replace *project_name* with your desired environment name and *3.x* with the
specific version of Python you want to use.
This package requires python 3.9 or a higher.

Activate the new environment by running:

.. code-block:: bash

conda activate project_name

**Step 2: Install plugin**

To install ``aixd_ara`` in your ``conda`` environment, use the following command:

.. code-block:: bash

conda install -c conda-forge aixd_ara

Finally, install the plugin in Rhino/GH using the following command:

.. code-block:: bash

python -m compas_rhino.install -v 7.0


Verify installation
===================

After installation, you can verify that the plugin has been successfully installed by running:

.. code-block:: bash

python -c "import aixd_ara; print(aixd_ara.__version__)"


If everything worked out correctly, the version of the installed plugin will be printed on
the screen, and you can start using the plugin in your projects.
2 changes: 1 addition & 1 deletion environment.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: aixd_gh
name: aixd_ara
channels:
- conda-forge
dependencies:
Expand Down
56 changes: 56 additions & 0 deletions install.bash
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
#!/usr/bin/env bash

while true; do
read -n 1 -p "Select Rhino version (7, 8, or Q to quit):" RHINO_VERSION
printf "\n";
case $RHINO_VERSION in
7* ) break;;
8* ) break;;
[Qq]* ) exit;;
* ) printf "Invalid Rhino version, please choose either 7 or 8.\n";;
esac
done

CONDA_HOME=$HOME/miniconda
CONDA_BIN=$CONDA_HOME/condabin
CONDA_ENV_NAME=aixd_ara

printf "[√] Starting ARA installation…\n"

printf "[ ] Checking conda…"

if ! command -V conda &> /dev/null
then
printf "\r[x] Conda not found, we will install Miniconda\n"
printf "[ ] Installing miniconda (Python distribution)…"
# curl https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -o ./miniconda.sh &> /dev/null
curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ./miniconda.sh &> /dev/null
bash ./miniconda.sh -b -u -p $CONDA_HOME &> /dev/null
printf "\r[√] Installing miniconda (Python distribution)…\n"

printf "[ ] Configuring miniconda for first use…"
$CONDA_BIN/conda init bash &> /dev/null
source $HOME/.bash_profile &> /dev/null
printf "\r[√] Configured miniconda for first use successfully\n"
else
CONDA_HOME=$(dirname $(dirname $CONDA_EXE))
printf "\r[√] Conda command found!\n"
fi

if { conda env list | grep $CONDA_ENV_NAME; } >/dev/null 2>&1; then
printf "[√] Virtual environment already exists! ($CONDA_ENV_NAME)\n"
else
printf "[√] Virtual environment not found, will create it now…\n"

printf "[ ] Creating virtual environment…"
conda create -c conda-forge -n $CONDA_ENV_NAME aixd aixd_ara compas flask python=3.9 -y &> /dev/null
printf "\r[√] Created virtual environment '$CONDA_ENV_NAME' successfully\n"
fi

printf "[ ] Activating virtual environment…"
source $CONDA_HOME/bin/activate $CONDA_ENV_NAME
printf "\r[√] Activated virtual environment successfully\n"

printf "[√] Activating environment '$CONDA_ENV_NAME' for Rhino…\n"
python -m compas_rhino.install -v $RHINO_VERSION.0
printf "\r[√] Successfully installed ARA on Rhino\n"
140 changes: 140 additions & 0 deletions install.cmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
@ECHO OFF
SETLOCAL EnableExtensions EnableDelayedExpansion

REM The following lines are courtesy of Windows' magnificent support for shell programming:
REM https://superuser.com/a/1166728
for /f %%a in ('copy /Z "%~dpf0" nul') do set "CR=%%a"
for /f %%a in ('"prompt $H&for %%b in (0) do rem"') do set "BS=%%a"

REM Retrieve current code page, before changing it
for /f "usebackq tokens=4" %%i in (`chcp`) do (
set _PREV_CHCP=%%i
)

SET CONDA_PATH=%UserProfile%\Miniconda3
SET CONDA_ENV_NAME=aixd_ara

REM Switch code page, so that we can print extended ASCII
CHCP 65001 >nul

:select_rhino_version
set RHINO_VERSION=
set /p RHINO_VERSION="Select Rhino version (7 or 8) [7]:"
if not "%RHINO_VERSION%"=="" set RHINO_VERSION=%RHINO_VERSION:~0,1%
if "%RHINO_VERSION%"=="" set RHINO_VERSION=7
if "%RHINO_VERSION%"=="7" goto valid_rhino_version
if "%RHINO_VERSION%"=="8" goto valid_rhino_version

ECHO Invalid Rhino version, please choose either 7 or 8.
GOTO select_rhino_version

:valid_rhino_version

<nul set /p"=[√] Starting ARA installation..."
ECHO.

:check_conda_presence
<nul set /p"=[ ] Checking conda..."
WHERE conda >nul 2>&1

IF %ERRORLEVEL%==0 (
<nul set /p"=!BS!!CR![√] Conda command found!"
GOTO use_existing_conda
)
IF %ERRORLEVEL%==1 (
<nul set /p"=!BS!!CR![x] Conda not found, we will install Miniconda"
)

ECHO.

<nul set /p"=[ ] Installing miniconda (Python distribution)..."
CALL curl -S -s -O https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe
IF %ERRORLEVEL% neq 0 GOTO miniconda_download_failed
SET CONDA_COMMAND=%CONDA_PATH%\condabin\conda

REM The last argument must NOT be quoted according to the conda docs, and that works even for paths with spaces in them
START /wait /min "Starting miniconda installation..." "Miniconda3-latest-Windows-x86_64.exe" /InstallationType=JustMe /S /D=%CONDA_PATH%
IF %ERRORLEVEL%==2 (
<nul set /p"=!BS!!CR![√] Miniconda seems to be already installed, will skip step and continue..."
ECHO.
GOTO compas_install
)
IF %ERRORLEVEL% neq 0 GOTO miniconda_install_failed
<nul set /p"=!BS!!CR![√] Installing miniconda (Python distribution)..."
ECHO.

:compas_install
<nul set /p"=[ ] Looking for virtual environment (%CONDA_ENV_NAME%)..."
CALL "%CONDA_COMMAND%" activate %CONDA_ENV_NAME% >nul 2>&1
IF %ERRORLEVEL%==0 (
<nul set /p"=!BS!!CR![√] Virtual environment already exists! (%CONDA_ENV_NAME%)"
ECHO.
GOTO compas_install_to_rhino
)
<nul set /p"=!BS!!CR![√] Virtual environment not found, will create it now... "
ECHO.

<nul set /p"=[ ] Creating virtual environment..."
CALL "%CONDA_COMMAND%" create -c conda-forge -n %CONDA_ENV_NAME% aixd aixd_ara compas flask python=3.9 -y >nul 2>&1
<nul set /p"=!BS!!CR![√] Created virtual environment '%CONDA_ENV_NAME%' successfully"
ECHO.

:conda_activate_virtual_env
ECHO ON
<nul set /p"=[ ] Activating virtual environment..."
CALL "%CONDA_COMMAND%" activate %CONDA_ENV_NAME%
IF %ERRORLEVEL% neq 0 GOTO conda_activate_failed
<nul set /p"=!BS!!CR![√] Activated virtual environment successfully"
ECHO.

:pip_install_deps
<nul set /p"=[ ] Installing pip tools..."
python -m pip install aixd_ara-0.1.0-py2.py3-none-any.whl -q
@REM python -m pip install black flake8 isort pytest rhino-stubs -q
IF %ERRORLEVEL% neq 0 GOTO pip_install_deps_failed
<nul set /p"=!BS!!CR![√] Installed pip tools successfully"
ECHO.

:compas_install_to_rhino
<nul set /p"=[√] Activating environment '%CONDA_ENV_NAME%' for Rhino..."
ECHO.
<nul set /p"=[√] Environment location: %CONDA_PREFIX%"
python -m compas_rhino.install -v %RHINO_VERSION%.0
<nul set /p"=[√] Successfully installed ARA on Rhino"
ECHO.
GOTO end_of_installer

:use_existing_conda
for /f "tokens=* delims=" %%a in ('where conda') do (
set "CONDA_COMMAND=%%a"
goto found_conda
)
:found_conda
ECHO.
GOTO compas_install

:conda_activate_failed
ECHO.
ECHO Could not activate virtual environment. Exiting.
GOTO end_of_installer

:pip_install_deps_failed
ECHO.
ECHO Could not install development tools. Exiting.
GOTO end_of_installer

:miniconda_install_failed
ECHO.
ECHO Could not install miniconda. Exiting.
GOTO end_of_installer

:miniconda_download_failed
ECHO.
ECHO Could not download miniconda. Exiting.
GOTO end_of_installer

:end_of_installer
SET _ERRORLEVEL=%ERRORLEVEL%
CHCP %_PREV_CHCP% >nul
PAUSE
EXIT /B %_ERRORLEVEL%
Binary file added install.zip
Binary file not shown.
5 changes: 5 additions & 0 deletions src/aixd_ara/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
__author__ = ["Aleksandra Apolinarska"]
__copyright__ = "Copyright (c) 2023-2024 ETH Zurich, Gramazio Kohler Research"
__license__ = "MIT License"
__email__ = "[email protected]"
__version__ = "0.1.0"
Loading