README.md

   1 # I am car, too
   2 *I am car, too* puts together multiple libraries and run some automated parking
   3 tests.
   4
   5 # License
   6 The project is published under [MIT License][1].
   7
   8 [1]: ./LICENSE
   9
  10 # Build
  11 To build the project run the following commands:
  12 ```
  13 mkdir build
  14 cd build
  15 cmake ../
  16 make
  17 ```
  18
  19 To build with ninja:
  20 ```
  21 mkdir build
  22 cd build
  23 cmake -DCMAKE_BUILD_TYPE=Release -G Ninja ../
  24 ninja -v
  25 ```
  26
  27 ## Required libraries
  28 - `libjsoncpp-dev`
  29 - `libpsp` (depends on `libbcar`, `libpslot`)
  30 - `librrts` (depends on `libbcar`)
  31
  32 # Tests
  33 Files in `src/` folder named `testX.cc` where `X` is integer are tests. All
  34 tests expects JSON fromatted *scenario* on standard input and outputs JSON
  35 formatted *plan* on standard output. Both, *scenario* and *plan* can be plotted
  36 with `plot_json_objects_scenario.py` script.
  37
  38 ## JSON formatted *scenario*
  39 The following properties are expected:
  40 - `init`: list of 3 numbers (`x`, `y`, `heading`).
  41 - `obst`: list of polygon obstacles, where polygon obstacle is list of
  42   coordinates, and coordinate is a list of 2 numbers (`x`, `y`).
  43 - `slot`: list of parking slots, where parking slot is a list of 4 coordinates,
  44   and coordinate is a list of 2 numbers (`x`, `y`).
  45
  46 ## JSON formatted *plan*
  47 The following properties are expected to extend *scenario* properties:
  48 - `goal`: list of 3 numbers (`x`, `y`, `heading`).
  49 - `goals`: list of possible goals `[(x, y, h), ...]`.
  50 - `path`: list of poses, where pose is list of 3 numbers (`x`, `y`, `heading`).
  51
  52 ## JSON formatted *stats*
  53 The following are expected in the output along with *plan*:
  54 - `time`: elapsed time.
  55 - `iterations`: number of iterations of algorithm.
  56 - `cost`: path cost.
  57 - `cusps-in-path`: the number of nodes with direction change in path.
  58 - `connecteds-in-path`: the number of nodes almost same (connected) in path.
  59 - `nodes`: overall number of nodes.
  60
  61 ## Test files
  62 There is a list of test files and what they include:
  63 - `test14.cc`: cute, grid, RS-heur, dijkstra (`ce9`).
  64 - `test13.cc`: cute, grid, RS-RS, dijkstra (`ce8`).
  65 - `test12.cc`: cute collision, grid structure, RS for both -- build and search
  66   cost (`ce6`).
  67 - `test11.cc`: cute collision, grid structure, RS for build, Matej's heuristics
  68   for search cost (`ce4`).
  69 - `test10.cc`: use [behavior tree][].
  70 - `test9.cc`: cute collision, grid structure, RS for build, Euclidean for
  71   search, path optimization (`ce7`).
  72 - `test8.cc`: cute collision, grid structure, RS for build, Euclidean for
  73   search (`ce5`).
  74 - `test7.cc`: pure RRT\* run in 1 second interval multiple times.
  75 - `test6.cc`: cute collision, Reeds and Shepp for both -- build and search
  76   cost (`ce3`).
  77 - `test5.cc`: cute collision, Reeds and Shepp for build cost, Euclidean
  78   distance for search cost (`ce2`).
  79 - `test4.cc`: cute collision, Reeds and Shepp for build cost, Matej's
  80   heuristics for search cost (`ce1`).
  81 - `test3.cc`: RRT\* with [cute c2][] library for collision detection.
  82 - `test2.cc`: rapidly-exploring random tree star.
  83 - `test1.cc`: parking slot planner.
  84 - `test-template.cc`: template for tests.
  85
  86 [cute c2]: https://github.com/RandyGaul/cute_headers/blob/master/cute_c2.h
  87 [behavior tree]: https://github.com/arvidsson/BrainTree
  88
  89 # Contribute
  90 Use [OneFlow][3] branching model and keep the [changelog][4].
  91
  92 Write [great git commit messages][5]:
  93 1. Separate subject from body with a blank line.
  94 2. Limit the subject line to 50 characters.
  95 3. Capitalize the subject line.
  96 4. Do not end the subject line with a period.
  97 5. Use the imperative mood in the subject line.
  98 6. Wrap the body at 72 characters.
  99 7. Use the body to explain what and why vs. how.
 100
 101 When adding feature or hotfix, use [Test-driven development (TDD)][2]:
 102 1. Add tests to `ut` folder, add methods declaration, basic structure.
 103 2. Run tests (just `make` in `build` folder), check that tests *fail*.
 104 3. Implement functionality.
 105 4. Run tests, check that tests *pass*.
 106 5. Refactor.
 107
 108 [2]: https://en.wikipedia.org/wiki/Test-driven_development
 109 [3]: https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow
 110 [4]: ./CHANGELOG.md
 111 [5]: https://chris.beams.io/posts/git-commit/
 112
 113 # Documentation
 114 The documentation is generated by Doxygen, at least version `1.8.15` is needed.
 115 Just run `doxygen` in the project root directory.