city_retrofit/MACOS_INSTALL.md

# Prepare your environment

Download the latest version of python and Microsoft c++ redistributable

* [Microsoft C++ redistributable](https://www.microsoft.com/en-ca/download/details.aspx?id=48145)
* [Python environment](https://www.python.org/downloads/)

# Get the code

1. First thing you will need is an editor for your source code, that's a personal choice, but we would like to recommend PyCharm community edition, an excellent open-source python editor. [PyCharm Community edition](https://www.jetbrains.com/pycharm/download/download-thanks.html?platform=windows&code=PCC)

2. Run the installer, and follow the installation instructions for PyCharm, you may change a few options, but the default ones should be fine.

3. Open PyCharm and click on **"Get from Version Control"**.

![pycharm welcome screen](docs/img_windows_install/img_0.png)

You can find it also at VCS -> Get from Version Control...

![pycharm get from version control](docs/img_windows_install/img_6.png)


4. Select Git as the version control, and set the URL to [libs repository](https://rs-loy-gitlab.concordia.ca/Guille/libs.git) as shown in the picture.
At the website, copy the URL from Clone -> Clone with HTTPS.

![pycharm get from version control screen](docs/img_windows_install/img_1.png)


You may need to install Git, by clicking at ***Download and install***. 
If that message does not appear is because you have it already installed in your computer.

5. Click Clone to download CERC libs source code. You will end with a project like this:


![pycharm project screen](docs/img_windows_install/img_2.png)

6. To create your working branch you need rights to edit that project. Please, talk to Guillermo (guillermo.gutierrezmorote@concordia.ca) 
or Koa (kekoa.wells@concordia.ca) to get those rights. Once you have them, right-click on the project folder (libs) -> Git -> Repository -> Branches:

![create new branch 1](docs/img_windows_install/img_9.png)

And then + New Branch:

![create new branch 2](docs/img_windows_install/img_10.png)

Give a name to your branch and open the tab Git at the down-left corner. Right-click on your branch and push.

![push new branch 1](docs/img_windows_install/img_11.png)

![push new branch 2](docs/img_windows_install/img_12.png)

Check that your branch appears in the Remote list:

![check all set](docs/img_windows_install/img_13.png)

If your branch is there, you are done with this part.

# Configure PyCharm

We use two spaces as a tab instead of standard [pep8](https://www.python.org/dev/peps/pep-0008/) four spaces indentation.
This option can be configured in PyCharm at the settings screen, as shown in the picture.

![pycharm configuration screen](docs/img_windows_install/img_5.png)


# Start your project

1. At our Git (https://rs-loy-gitlab.concordia.ca/), click on New project:

![git new project screen](docs/img_windows_install/img_14.png)

The create a black project with the desired name (remember to follow our ![Coding Style](PYGUIDE.md)). 
Be sure that Initialize repository with a README is selected, and ideally, that the Visibility Level is Public. 

![git give a name](docs/img_windows_install/img_15.png)

And finally, clone it following the same steps as for ![libs](WINDOWS_INSTALL.md#get-the-code) (steps 3 to 5).

2. Go to project settings and add the libs project to your own, by clicking on Add Content Root:

![pycharm new project screen](docs/img_windows_install/img_4.png)

![pycharm add libs](docs/img_windows_install/img_7.png)

3. Add your first file to your project and click on install requirements to automatically download all the dependencies (in blue at top-right corner).

![pycharm add dependencies](docs/img_windows_install/img_8.png)

4. When all the dependencies are satisfied, you are all set to start importing your first city model.

Add the following code to your main.py

```python

from imports.geometry_factory import GeometryFactory

city = GeometryFactory('citygml', 'myfile.gml').city
```

5. Always remember to push your own project changes as the last thing you do before ending your working day! 
First, commit your changes by clicking on the green check at the top-right corner of Pycharm. Add a comment that explains briefly your changes. 
Then, pull by clicking on the blue arrow to be sure that there are no conflicts between your version (local) and the remote one (gitlab). 
Once the conflicts are solved and the merge in local is done, push the changes by clicking on the green arrow.