diff --git a/.travis.yml b/.travis.yml index 62d7b54af..5f123a019 100644 --- a/.travis.yml +++ b/.travis.yml @@ -24,4 +24,4 @@ matrix: packages: - cppcheck script: - - cppcheck Unreal/CarlaUE4/Source Unreal/CarlaUE4/Plugins/Carla/Source Util/ -iUtil/Build -iUtil/CarlaServer/source/carla/server/carla_server.pb.cc --quiet --error-exitcode=1 --enable=warning + - cppcheck . -iBuild -i.pb.cc --error-exitcode=1 --enable=warning --quiet diff --git a/Docs/CODE_OF_CONDUCT.md b/Docs/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..45904febb --- /dev/null +++ b/Docs/CODE_OF_CONDUCT.md @@ -0,0 +1,73 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, race, +religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at [INSERT EMAIL ADDRESS]. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org diff --git a/Docs/CONTRIBUTING.md b/Docs/CONTRIBUTING.md index 3438010e1..1f0c50781 100644 --- a/Docs/CONTRIBUTING.md +++ b/Docs/CONTRIBUTING.md @@ -1,23 +1,25 @@ Contributing to CARLA ===================== -> _This document is a work in progress and might be incomplete._ - We are more than happy to accept contributions! How can I contribute? * Reporting bugs * Feature requests + * Improving documentation * Code contributions Reporting bugs -------------- -Use our [issue section](issueslink) on GitHub. Please check before that the -issue is not already reported. +Use our [issue section][issueslink] on GitHub. Please check before that the +issue is not already reported, and make sure you have read our +[Documentation][docslink] and [FAQ][faqlink]. [issueslink]: https://github.com/carla-simulator/carla/issues +[docslink]: http://carla.readthedocs.io +[faqlink]: http://carla.readthedocs.io/en/latest/faq/ Feature requests ---------------- @@ -28,6 +30,25 @@ your request as a new issue. [frlink]: https://github.com/carla-simulator/carla/issues?q=is%3Aissue+is%3Aopen+label%3A%22feature+request%22 +Improving documentation +----------------------- + +If you feel something is missing in the documentation, please don't hesitate to +open an issue to let us know. Even better, if you think you can improve it +yourself, it would be a great contribution to the community! + +We build our documentation with [MkDocs](http://www.mkdocs.org/) based on the +Markdown files inside the "Docs" folder. You can either directly modify them on +GitHub or locally in your machine. + +Once you are done with your changes, please submit a pull-request. + +**TIP:** You can build and serve it locally by running `mkdocs` in the project's +main folder + + $ sudo pip install mkdocs + $ mkdocs serve + Code contributions ------------------ @@ -52,34 +73,33 @@ current documentation if you feel confident enough. #### Coding standard -Please follow the current coding style when submitting new code. - -###### General - - * Use spaces, not tabs. - * Avoid adding trailing whitespace as it creates noise in the diffs. - * Comments should not exceed 80 columns, code may exceed this limit a bit in rare occasions if it results in clearer code. - -###### Python - - * All code must be compatible with Python 2.7, 3.5, and 3.6. - * [Pylint](https://www.pylint.org/) should not give any error or warning (few exceptions apply with external classes like `numpy`, see our `.pylintrc`). - * Python code follows [PEP8 style guide](https://www.python.org/dev/peps/pep-0008/) (use `autopep8` whenever possible). - -###### C++ - - * Compilation should not give any error or warning (`clang++ -Wall -Wextra -std=C++14`). - * Unreal C++ code (CarlaUE4 and Carla plugin) follow the [Unreal Engine's Coding Standard](https://docs.unrealengine.com/latest/INT/Programming/Development/CodingStandard/) with the exception of using spaces instead of tabs. - * CarlaServer uses [Google's style guide](https://google.github.io/styleguide/cppguide.html). +Please follow the current [coding standard](coding_standard.md) when submitting +new code. #### Pull-requests Once you think your contribution is ready to be added to CARLA, please submit a -pull-request to the `dev` branch. +pull-request. Try to be as descriptive as possible when filling the pull-request description. +Adding images and gifs may help people to understand your changes or new +features. Please note that there are some checks that the new code is required to pass before we can do the merge. The checks are automatically run by the continuous integration system, you will see a green tick mark if all the checks succeeded. If you see a red mark, please correct your code accordingly. + +###### Checklist + + + + - [ ] Your branch is up-to-date with the `master` branch and tested with latest changes + - [ ] Extended the README / documentation, if necessary + - [ ] Code compiles correctly + - [ ] All tests passing + - [ ] `make check` + - [ ] `pylint --disable=R,C --rcfile=PythonClient/.pylintrc PythonClient/carla PythonClient/*.py` + - [ ] `cppcheck . -iBuild -i.pb.cc --enable=warning` diff --git a/Docs/coding_standard.md b/Docs/coding_standard.md new file mode 100644 index 000000000..f03eae186 --- /dev/null +++ b/Docs/coding_standard.md @@ -0,0 +1,25 @@ +Coding standard +=============== + +> _This document is a work in progress and might be incomplete._ + +General +------- + + * Use spaces, not tabs. + * Avoid adding trailing whitespace as it creates noise in the diffs. + * Comments should not exceed 80 columns, code may exceed this limit a bit in rare occasions if it results in clearer code. + +Python +------ + + * All code must be compatible with Python 2.7, 3.5, and 3.6. + * [Pylint](https://www.pylint.org/) should not give any error or warning (few exceptions apply with external classes like `numpy`, see our `.pylintrc`). + * Python code follows [PEP8 style guide](https://www.python.org/dev/peps/pep-0008/) (use `autopep8` whenever possible). + +C++ +--- + + * Compilation should not give any error or warning (`clang++ -Wall -Wextra -std=C++14`). + * Unreal C++ code (CarlaUE4 and Carla plugin) follow the [Unreal Engine's Coding Standard](https://docs.unrealengine.com/latest/INT/Programming/Development/CodingStandard/) with the exception of using spaces instead of tabs. + * CarlaServer uses [Google's style guide](https://google.github.io/styleguide/cppguide.html). diff --git a/Docs/faq.md b/Docs/faq.md index 340e09683..b87bd32d2 100644 --- a/Docs/faq.md +++ b/Docs/faq.md @@ -1,7 +1,20 @@ -CARLA F.A.Q. -============ + +
+
+ What is the recommended hardware to run CARLA? +
-#### What is the expected disk space needed for building CARLA? +CARLA is a very performance demanding software, at the very minimum you would +need a computer with a dedicated GPU capable of running Unreal Engine. See +[Unreal Engine's recommended hardware](https://wiki.unrealengine.com/Recommended_Hardware). + +
+ + +
+
+ What is the expected disk space needed for building CARLA? +
Building CARLA from source requires about 15GB of disk space, not counting Unreal Engine installation. @@ -10,24 +23,27 @@ However, you will also need to build and install Unreal Engine, which on Linux requires much more disk space as it keeps all the intermediate files, [see this thread](https://answers.unrealengine.com/questions/430541/linux-engine-size.html). -#### Is it possible to dump images from the CARLA server view? +
-Yes, this is an Unreal Engine feature. You can dump the images of the server -camera by running CARLA with - - $ ./CarlaUE4.sh -benchmark -fps=30 -dumpmovie - -Images are saved to "CarlaUE4/Saved/Screenshots/LinuxNoEditor". - -#### I downloaded CARLA source from GitHub, where is the "CarlaUE4.sh" script? + +
+
+ I downloaded CARLA source from GitHub, where is the "CarlaUE4.sh" script? +
There is no "CarlaUE4.sh" script in the source version of CARLA, you need to -follow the instructions in the [documentation](http://carla.readthedocs.io) on +follow the instructions in the [documentation](http://carla.readthedocs.io) for building CARLA from source. Once you open the project in the Unreal Editor, you can hit Play to test CARLA. -#### Can I skip the download step in Setup.sh? +
+ + +
+
+ Setup.sh fails to download content, can I skip this step? +
It is possible to skip the download step by passing the `-s` argument to the setup script @@ -40,9 +56,99 @@ for instructions or run $ ./Update.sh -s -#### How can I create a binary version of CARLA? +
+ + +
+
+ Can I run the server from within Unreal Editor? +
+ +Yes, you can connect the Python client to a server running within Unreal Editor +as if it was the standalone server. + +Go to **"Unreal/CarlaUE4/Config/CarlaSettings.ini"** (this file should have been +created by the Setup.sh) and enable networking. If for whatever reason you don't +have this file, just create it and add the following + +```ini +[CARLA/Server] +UseNetworking=true +``` + +Now when you hit Play the editor will hang until a client connects. + +
+ + +
+
+ Why Unreal Editor hangs after hitting Play? +
+ +This is most probably happening because CARLA is starting in server mode. Check +your **"Unreal/CarlaUE4/Config/CarlaSettings.ini"** and set + +```ini +[CARLA/Server] +UseNetworking=false +``` + +
+ + +
+
+ How can I create a binary version of CARLA? +
To compile a binary (packaged) version of CARLA, open the CarlaUE4 project with -Unreal Editor, go to the menu “File -> Package Project”, and select your +Unreal Editor, go to the menu "File -> Package Project", and select your platform. This takes a while, but in the end it should generate a packaged version of CARLA to execute without Unreal Editor. + +
+ + +
+
+ Why do I have very low FPS when running the server in Unreal Editor? +
+ +UE4 Editor goes to a low performance mode when out of focus. It can be disabled +in the editor preferences. Go to "Edit->Editor Preferences->Performance" and +disable the "Use Less CPU When in Background" option. + +
+ + +
+
+ Is it possible to dump images from the CARLA server view? +
+ +Yes, this is an Unreal Engine feature. You can dump the images of the server +camera by running CARLA with + + $ ./CarlaUE4.sh -benchmark -fps=30 -dumpmovie + +Images are saved to "CarlaUE4/Saved/Screenshots/LinuxNoEditor". + +
+ + +
+
+ Fatal error: 'version.h' has been modified since the precompiled header. +
+ +This happens from time to time due to Linux updates. It is possible to force a +rebuild of all the project files with + + $ cd Unreal/CarlaUE4/ + $ make CarlaUE4Editor ARGS=-clean + $ make CarlaUE4Editor + +It takes a long time but fixes the issue. Sometimes a reboot is also needed. + +
diff --git a/Docs/how_to_run.md b/Docs/how_to_run.md index 47412a339..613d44b5a 100644 --- a/Docs/how_to_run.md +++ b/Docs/how_to_run.md @@ -38,15 +38,9 @@ The "carla" Python module provides a basic API for communicating with the CARLA server. In the "PythonClient" folder we provide a couple of examples on how to use this API. We recommend Python 3, but they are also compatible with Python 2. -The basic functionality requires only the protobuf module to be installed +Install the dependencies with - $ sudo apt-get install python3 python3-pip - $ sudo pip3 install protobuf - -However, other operations as handling images require some extra modules, and the -"manual_control.py" example requires pygame - - $ sudo pip3 install numpy Pillow pygame + $ pip install -r PythonClient/requirements.txt The script "PythonClient/client_example.py" provides basic functionality for controlling the vehicle and saving images to disk. Run the help command to see diff --git a/Docs/index.md b/Docs/index.md index 44565e3aa..40491ec84 100644 --- a/Docs/index.md +++ b/Docs/index.md @@ -9,7 +9,6 @@ CARLA Documentation * [Cameras and sensors](cameras_and_sensors.md) * [Benchmark](benchmark.md) * [F.A.Q.](faq.md) - * [Troubleshooting](troubleshooting.md) #### Building from source @@ -20,6 +19,8 @@ CARLA Documentation #### Contributing * [Contribution guidelines](CONTRIBUTING.md) + * [Coding standard](coding_standard.md) + * [Code of conduct](CODE_OF_CONDUCT.md) #### Development diff --git a/Docs/issue_template.md b/Docs/issue_template.md new file mode 100644 index 000000000..024be87e5 --- /dev/null +++ b/Docs/issue_template.md @@ -0,0 +1,9 @@ + diff --git a/Docs/pull_request_template.md b/Docs/pull_request_template.md new file mode 100644 index 000000000..3a5c29258 --- /dev/null +++ b/Docs/pull_request_template.md @@ -0,0 +1,32 @@ + + +#### Description + + + +Fixes # + +#### Where has this been tested? + + * **Platform(s):** ... + * **Python version(s):** ... + * **Unreal Engine version(s):** ... + +#### Possible Drawbacks + + diff --git a/Docs/troubleshooting.md b/Docs/troubleshooting.md deleted file mode 100644 index 106f2e687..000000000 --- a/Docs/troubleshooting.md +++ /dev/null @@ -1,41 +0,0 @@ -Troubleshooting -=============== - -#### Editor hangs after hitting Play - -This is most probably happening because CARLA is started in server mode. Check -in your CarlaSettings.ini file ("./Unreal/CarlaUE4/Config/CarlaSettings.ini") -and set - -```ini -[CARLA/Server] -UseNetworking=false -``` - -#### Very low FPS in editor when not in focus - -UE4 Editor goes to a low performance mode when out of focus. It can be disabled -in the editor preferences. Go to "Edit->Editor Preferences->Performance" and -disable the "Use Less CPU When in Background" option. - -#### Fatal error: file '/usr/include/linux/version.h' has been modified since the precompiled header - -This happens from time to time due to Linux updates. It is possible to force a -rebuild of all the project files with - - $ cd Unreal/CarlaUE4/ - $ make CarlaUE4Editor ARGS=-clean - $ make CarlaUE4Editor - -#### Setup.sh fails to download content - -It is possible to skip the download step by passing the `-s` argument to the -setup script - - $ ./Setup.sh -s - -Bear in mind that if you do so, you are supposed to manually download and -extract the content package yourself, check out the last output of the Setup.sh -for instructions or run - - $ ./Update.sh -s diff --git a/README.md b/README.md index 82b6d64ab..f2a803b6d 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ If you want to benchmark your model in the same conditions as in our CoRL’17 p News ---- +- 22.01.2018 Job opening: [C++ (UE4) Programmer](https://drive.google.com/open?id=1Hx0eUgpXl95d4IL9meEGhJECgSRos1T1). - 28.11.2017 CARLA 0.7.0 released: [change log](https://github.com/carla-simulator/carla/blob/master/CHANGELOG.md#carla-070), [release](https://github.com/carla-simulator/carla/releases/tag/0.7.0). - 15.11.2017 CARLA 0.6.0 released: [change log](https://github.com/carla-simulator/carla/blob/master/CHANGELOG.md#carla-060), [release](https://github.com/carla-simulator/carla/releases/tag/0.6.0). @@ -57,6 +58,42 @@ Felipe Codevilla, Antonio Lopez, Vladlen Koltun; PMLR 78:1-16 } ``` +Building CARLA +-------------- + +Use `git clone` or download the project from this page. Note that the master +branch contains the latest fixes and features, for the latest stable code may be +best to switch to the `stable` branch. + +Then follow the instruction at [How to build on Linux][buildlink]. + +Unfortunately we don't have yet official instructions to build on other +platforms, please check the progress for [Windows][issue21] and [Mac][issue150]. + +[buildlink]: http://carla.readthedocs.io/en/latest/how_to_build_on_linux +[issue21]: https://github.com/carla-simulator/carla/issues/21 +[issue150]: https://github.com/carla-simulator/carla/issues/150 + +Contributing +------------ + +Please take a look at our [Contribution guidelines][contriblink]. + +[contriblink]: http://carla.readthedocs.io/en/latest/CONTRIBUTING + +F.A.Q. +------ + +If you run into problems, check our +[FAQ](http://carla.readthedocs.io/en/latest/faq/). + +Jobs +---- + +We are currently looking for a new programmer to join our team + + * [C++ (UE4) Programmer](https://drive.google.com/open?id=1Hx0eUgpXl95d4IL9meEGhJECgSRos1T1) + License ------- diff --git a/mkdocs.yml b/mkdocs.yml index 204cff558..6144dc8ed 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,13 +11,14 @@ pages: - 'Cameras and sensors': 'cameras_and_sensors.md' - 'Benchmark': 'benchmark.md' - 'F.A.Q.': 'faq.md' - - 'Troubleshooting': 'troubleshooting.md' - Building from source: - 'How to build on Linux': 'how_to_build_on_linux.md' - 'How to build on Windows': 'how_to_build_on_windows.md' - 'How to add Automotive Materials': 'how_to_add_automotive_materials.md' - Contributing: - 'Contribution guidelines': 'CONTRIBUTING.md' + - 'Coding standard': 'coding_standard.md' + - 'Code of conduct': 'CODE_OF_CONDUCT.md' - Development: - 'Map customization': 'map_customization.md' - 'How to add assets': 'how_to_add_assets.md'