p71924506
/
carla
mirror of https://github.com/carla-simulator/carla.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #138 from carla-simulator/documentation 

Improvements to documentation
This commit is contained in:
Néstor Subirón 2018-01-23 10:46:10 +01:00 committed by GitHub
parent be996126ff b1a6ffc8e2
commit 45c878fbe4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 349 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.travis.yml
View File

@ -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

73
Docs/CODE_OF_CONDUCT.md Normal file
View File

@ -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

68
Docs/CONTRIBUTING.md
View File

@ -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
<!--
If you modify this list please keep it up-to-date with pull_request_template.md
-->
- [ ] 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`

25
Docs/coding_standard.md Normal file
View File

@ -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).

138
Docs/faq.md
View File

@ -1,7 +1,20 @@
CARLA F.A.Q.
============
<!-- ======================================================================= -->
<details>
<summary><h5 style="display:inline">
What is the recommended hardware to run CARLA?
</h4></summary>
#### 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).
</details>
<!-- ======================================================================= -->
<details>
<summary><h5 style="display:inline">
What is the expected disk space needed for building CARLA?
</h4></summary>
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?
</details>
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?
<!-- ======================================================================= -->
<details>
<summary><h5 style="display:inline">
I downloaded CARLA source from GitHub, where is the "CarlaUE4.sh" script?
</h4></summary>
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?
</details>
<!-- ======================================================================= -->
<details>
<summary><h5 style="display:inline">
Setup.sh fails to download content, can I skip this step?
</h4></summary>
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?
</details>
<!-- ======================================================================= -->
<details>
<summary><h5 style="display:inline">
Can I run the server from within Unreal Editor?
</h4></summary>
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.
</details>
<!-- ======================================================================= -->
<details>
<summary><h5 style="display:inline">
Why Unreal Editor hangs after hitting Play?
</h4></summary>
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
```
</details>
<!-- ======================================================================= -->
<details>
<summary><h5 style="display:inline">
How can I create a binary version of CARLA?
</h4></summary>
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.
</details>
<!-- ======================================================================= -->
<details>
<summary><h5 style="display:inline">
Why do I have very low FPS when running the server in Unreal Editor?
</h4></summary>
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.
</details>
<!-- ======================================================================= -->
<details>
<summary><h5 style="display:inline">
Is it possible to dump images from the CARLA server view?
</h4></summary>
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".
</details>
<!-- ======================================================================= -->
<details>
<summary><h5 style="display:inline">
Fatal error: 'version.h' has been modified since the precompiled header.
</h4></summary>
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.
</details>

10
Docs/how_to_run.md
View File

@ -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

3
Docs/index.md
View File

@ -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

9
Docs/issue_template.md Normal file
View File

@ -0,0 +1,9 @@
<!--
Thanks for contributing to CARLA!
If you are asking a question please make sure your question was not asked before
by searching among the existing issues. Also make sure you have read our
documentation and FAQ at carla.readthedocs.io.
-->

32
Docs/pull_request_template.md Normal file
View File

@ -0,0 +1,32 @@
<!--
Thanks for sending a pull request! Please make sure you click the link above to
view the contribution guidelines, then fill out the blanks below.
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`
-->
#### Description
<!-- Please explain the changes you made here as detailed as possible. -->
Fixes # <!-- If fixes an issue, please add here the issue number. -->
#### Where has this been tested?
* **Platform(s):** ...
* **Python version(s):** ...
* **Unreal Engine version(s):** ...
#### Possible Drawbacks
<!-- What are the possible side-effects or negative impacts of the code change? -->

41
Docs/troubleshooting.md
View File

@ -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

37
README.md
View File

@ -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
-------

3
mkdocs.yml
View File

@ -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'