diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4d230b1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +## Contributing + +### Step 1: Fork the Repository + +1. Navigate to the main repository on GitHub: **[UTK Repository](https://github.com/urban-toolkit/utk)**. +2. Click the **Fork** button in the top-right corner to create a copy of the repository under your GitHub account. +### Step 2: Make Your Changes + +1. Clone your forked repository to your local machine +2. Create a new branch for your changes (optional but recommended): + +```bash + git checkout -b your-feature-branch +``` +### Step 3: Commit Your Changes + +1. Stage the changes you made: + ```bash + git add + ``` +2. Commit your changes with a descriptive message: + ```bash + git commit -m "Description of changes made" + ``` +3. Push your changes to your forked repository: + ```bash + git push origin your-feature-branch + ``` +### Step 4: Create a Pull Request + +1. Go to the **main GitHub page of your fork**. +2. If your fork is ahead of the main repository, you'll see a message indicating it is **X commits ahead of UTK:main**. +3. Click the **Contribute** button. +4. Select **Open pull request**. +5. Add a descriptive title and details about the changes you made. +6. Submit the pull request. +### Step 5: Wait for response + +- Once your pull request is submitted, maintainers will review your changes. Be prepared to discuss or update your pull request based on feedback. +- If requested, make additional changes and update the pull request by committing and pushing to the same branch in your fork. + +--- + +### Guidelines for Contributions + +- Ensure your changes do not break existing functionality. +- Adhere to the coding style and conventions used in the project. +- Write clear commit messages. + +--- + +Thank you for your contribution! If you have any questions, feel free to reach out by creating an issue or contacting the maintainers directly. diff --git a/README.md b/README.md index 92b8056..9e73627 100644 --- a/README.md +++ b/README.md @@ -33,14 +33,14 @@ IEEE Transactions on Visualization and Computer Graphics, 2024 ## Table of contents 1. [Features](#features) -2. [Installation and quick start](#installation-and-quick-start) - 1. [UTK backend](#utk-backend) - 2. [UTK frontend](#utk-frontend) +2. [Setting up to run utk locally](#setting-up-to-run-utk-locally) + - [Using built In Python command](#using-built-in-python-command) + - [Using `conda` environment manager](#using-conda-environment-manager) 3. [Tutorials](#tutorials) 4. [Development](#development) - 1. [Slack channel](#slack-channel) -6. [Other resources](#other-resources) -7. [Team](#team) + 1. [Slack channel](#slack-channel) +5. [Other resources](#other-resources) +6. [Team](#team) ## Features - Easy integration of physical and thematic layers. @@ -53,55 +53,98 @@ IEEE Transactions on Visualization and Computer Graphics, 2024 UTK has been tested on Linux (Ubuntu 23.04), Windows 10 & 11, and MacOS 13. -## Installation and quick start - -UTK leverages several spatial packages, such as Geopandas, OSMnx, Osmium, Shapely. To facilite the installation of UTK, we have made it available through pip, only requiring the following commands in a terminal / command prompt: - -```console -pip install utk -``` - -UTK requires Python 3.9, 3.10 and 3.11 (there is an [issue](https://stackoverflow.com/questions/77364550/attributeerror-module-pkgutil-has-no-attribute-impimporter-did-you-mean) with 3.12 that is on our TODO list to solve). If you are having problems installing UTK in Mac OSX because of Osmium, make sure you have CMake installed as well (e.g., through [conda](https://anaconda.org/anaconda/cmake) or [Homebrew](https://formulae.brew.sh/formula/cmake)). - -A detailed description of UTK's capabilities can be found in our [paper](https://arxiv.org/abs/2308.07769), but generally speaking UTK is divided into two components: a backend component, accessible through UTK's Python library, and a frontend component, accessible through a web interface. - -### UTK backend - -UTK's backend is available through our Python library. For example, using a Jupyter Notebook, it can be imported with: - -```python -import utk -``` - -To download data for Manhattan, NY, you only need to then: +## Setting up to run utk locally + +To run UTK locally, you must configure a Python environment on your machine. Without this step, you will not be able to launch the UTK server and the editor itself. Configuring python environment can be done using Conda environment manager or Built-In `venv` command. Here we will go over these two methods for setting up UTK. + +
+ Using built In Python command + + ## Using built In Python command + ### **Install Python** + First you need to ensure correct Python version is installed. Currently supported python versions are 3.9. 3.10, 3.11. If you don't have python installed follow instructions on [Download Python | Python.org](https://www.python.org/downloads/) and install python version 3.10 on your machine. You can check if python is installed by running the following commands + ```SHELL + python3 --version + ``` + ### **Create a Virtual Environment** + Next step is to set up a new virtual environment for UTK to run in. We will use `venv` command for that. `venv` as well as `pip` comes packaged with all Python versions after 3.0, so there is no need to install them. + - Choose the location where you will work with UTK: + - Mac/Linux: `/Users/*username*/Desktop/Repos/UTK_ENV` + - Windows: `C:\Users\YourUsername\Desktop\UTK_ENV` + - Run the following commands to create a virtual environment named `UTK_ENV` + Mac/Linux: + ```SHELL + python3 -m venv /Users/*username*/Desktop/UTK_ENV + + ``` + Windows: + ```SHELL + python3 -m venv C:\Users\YourUsername\Desktop\UTK_ENV + + ``` + ### **Activate the Virtual Environment** + After the environment is set up activate the environment using the following command: + Mac/Linux: + ```SHELL + source /Users/*username*/Desktop/UTK_ENV/bin/activate + ``` + Windows: + ```SHELL + cd C:\Users\YourUsername\Desktop\UTK_ENV + C:\Users\YourUsername\Desktop\UTK_ENV\Scripts\activate + ``` + ### **Install Required Packages** + Once you are in the newly created environment, you need to install `utk` package as well as python kernel and jupyterLab. We can do that by running the following commands: + ```SHELL + pip3 install utk + pip3 install jupyterlab + pip install ipykernel + python -m ipykernel install --user --name=UTK_ENV + ``` + ### **Verify Installation** + Type the following code into the jupyter notebook and run it. If the code runs successfully, that means the setup is complete and you are ready to use utk. + ```SHELL + utk example + ``` + Go to your browser and type the following to acces the utk server. If successful you will see a view of manhattan with an editor in front of you. + ``` + http://localhost:5001 + ``` +
+ +
+ Using `conda` environment manager + + ## Using `conda` environment manager + +### **Install Conda** +First make sure conda is installed by installing it from the official website: [Download Anaconda Distribution | Anaconda](https://www.anaconda.com/download) +### **Create and activate a Conda Environment** +After having conda installed we can create a new environment to work in by running the following command: +```SHELL +conda create -n UTK_CONDA python=3.10 +conda activate UTK_CONDA ``` -uc = utk.OSM.load('Manhattan, NY', layers=['surface', 'parks', 'water', 'roads']) -uc.save('./manhattan') +### **Install Required Packages** +Once you are in the newly created environment, you need to install `utk` package as well as python kernel and jupyterLab. We can do that by running the following commands: +```SHELL +pip3 install utk +pip3 install jupyterlab +pip install ipykernel +python -m ipykernel install --user --name=UTK_CONDA ``` - -This will create a new folder (``manhattan``) with the downloaded and parsed OSM data. On top of that, UTK also offers functionalities to load data from shapefiles (``utk.physical_from_shapefile``), csv files (``utk.thematic_from_csv``), dataframes (``utk.thematic_from_df``), and also accumulate sunlight access values (``utk.data.shadow``). A detailed description of UTK's Python API can be found [here](https://github.com/urban-toolkit/utk/blob/master/API.md). - - -### UTK frontend - -UTK's frontend is available through the ``utk`` command. After the pip installation is complete, you can check a toy example with the following commands: - -```console +### **Verify Installation** +Type the following code into the jupyter notebook and run it. If the code runs successfully, that means the setup is complete and you are ready to use utk. +```SHELL utk example ``` - -UTK's toy example will then be accessible through ``localhost:5001``. After accessing it using a browser, you should see a grammar-defined visualization showing sunlight access per building: - -![UTK example](https://github.com/urban-toolkit/utk/blob/master/images/example_full.png?raw=true) - - -Beyong the simple example, you can also use the ``utk`` command to start and stop UTK's server: - -```console -utk start -utk stop +Go to your browser and type the following to acces the utk server. If successful you will see a view of manhattan with an editor in front of you. +``` +http://localhost:5001 ``` +
+## `utk` Command The ``utk`` command takes the following arguments: ``` usage: utk [-h] [-d [DATA]] [-b [BUNDLE]] [-g [GRAMMAR]] [-a [ADDRESS]] @@ -131,10 +174,54 @@ optional arguments: ``` Even though we offer support for a variety of arguments, most users will simply need to run the following to use data stored in a folder called ``./data/``: +## Loading custom data +
+ Loading your own data + +### Loading your own data +If there is a specific map section that you need to work with you can use the following steps: +1. Launch jupyterLab with: +```SHELL +jupyter-lab +``` + You will be prompted to select Python kernel. Select the kernel we created in previous tutorial. + + +2. Download the data from OSM into the specified folder. +```Python +uc = utk.OSM.load('Manhattan, NY', layers=['surface', 'parks', 'water', 'roads']) +uc.save('./manhattan') +``` + +This download will get all the data that you need to run utk. Folder with data should contain grammar.json, which is the file which will contain your visualisation -```console -utk start --data ./data +3. In the terminal launch utk server +```SHELL +utk start --data ./*downloaded_data* +``` + +4. Go to your browser and type. I successful you will see a view of manhattan with an editor in front of you. +``` +http://localhost:5001 +``` +
+ + +
+ Using pre-downloaded data + + ## Using pre-downloaded data +Some of our tutorials will provide a download link with a data file. In this case all you need to do is go to the folder in which the downloaded folder is located and do the following steps(Assuming you are in the correct environment): +1. In the terminal launch utk server +```SHELL +utk start --data ./*downloaded_data* +``` + +2. Go to your browser and type. I successful you will see a view of manhattan with an editor in front of you. +``` +http://localhost:5001 ``` +
After starting UTK's server and opening ``localhost:5001`` on a browser, you will see UTK's main interface, composed of a grammar editor (left) and map viewer (right). Adding new elements to the grammar specification on the right (e.g., new plots, new data) will automatically update the map viewer: