diff --git a/README.md b/README.md index 2741868db91a8542b8f78736fd448ceb9aaf08b4..495c4f2fa9ed3004c29cc62164c07a8fb396788e 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,94 @@ # road_description -## Description - This package contains the urdf and launch files to load road images, which can be used in simulation. -Developed at Institut de Robòtica i Informà tica Industrial (IRI, CSIC-UPC) (www.iri.upc.edu) -Contact: labrobotica@iri.upc.edu + + ## Installation -Clone the package inside a ROS workspace, although it will normally come within a rosinstall file. +Move to workspace: +``` +roscd && cd ../src +``` + +Clone the repository: +``` +git clone https://gitlab.iri.upc.edu/mobile_robotics/adc/simulator/road_description.git +``` + +Install all ROS dependencies with the following commands: +``` +roscd +cd .. +rosdep install -i -r --from-paths src +``` + +Compile all the ROS packages with the following commands: +``` +catkin_make +``` + +## Configuration + +No road image is provided in this repository due to its size. + +An example road image can be download from [here](https://drive.google.com/file/d/15bV7bQubtGe_wC1j8WgNNtduttExSHen/view?usp=sharing). + +To generate new road images, follow the next steps: + +* Create a new road or edit an existing one using the [OpenRoadEd](https://gitlab.iri.upc.edu/mobile_robotics/adc/openroaded) tool. See the documentation on this link for more information. +* Create a screenshot of the desired road. +* The screenshot is created as a 7000x7000 pixel image with a default resolution of 72 ppi (pixel per inch). Because of this fact, no matter what is the actual size of the real road, the screenshot equivalent size will be different. To *resize* the original image it is necessary to modify its ppi. To do so, compute the new ppi with the following equation, where *39.27* is the conversion from meters to inches: + +<img align="center" src="docs/images/ppi_conv.gif" alt="Equation to compute the required ppi of the image" width="201" height="42"> + +* To change the ppi of the original image, execute the following command (both the original and modified images must be PNG): +``` +convert <original_image> -density <new_ppi_value> -units PixelsPerInch <modified_image> +``` + +* This packages includes a script to create a link to the actual road image, so it is not necessary to copy it anywhere. See the [launch](#launch) section. + +## Launch + +This package file includes a launch file named spawn_road.launch which is intended to be included from other launch file that requires to spawn a road in a simulated Gazebo world. This launch file has two parameters: + +* **road_name**: (default=road) name of the road image to be used (without the .png extension). This name will also be used to name the nodes and topics associated with the road description. +* **road_size**: (default=15.0) size of the road in meters. At the moment only square road images are supported. +* **road_path**: (default=$(env HOME)/Downloads) path where the road image is located. +* **x** (default=0.0) x position where the road will placed in the simulated environment with respect to the parent frame. +* **y** (default=0.0) y position where the road will placed in the simulated environment with respect to the parent frame. +* **yaw** (default=0.0) orientation of the road with respect to the parent frame +* **parent** (default=map) parent reference frame used to place the road in the simulated environment. + +To spawn a road from an other launch file, include the following lines: +``` + <include file="$(find road_description)/launch/spawn.launch"> + <arg name="road_name" value="$(arg road_name)"/> + <arg name="road_size" value="$(arg road_size)"/> + <arg name="road_path" value="$(arg road_path)"/> + <arg name="x" value="$(arg x)"/> + <arg name="y" value="$(arg y)"/> + <arg name="yaw" value="$(arg yaw)"/> + <arg name="parent" value="$(arg parent)"/> + </include> +``` + +A test launch file is provided to visualize the road in RVIZ. Ti use it, execute the following command: + +``` +roslaunch road_description spawn_test.launch road_name:=<name of the road> road_path:=<path to the road> road_size:=<size of the road>` +``` + +## Disclaimer + +Copyright (C) Institut de Robòtica i Informà tica Industrial, CSIC-UPC. +Mantainer IRI labrobotics (labrobotica@iri.upc.edu) + +This package is distributed in the hope that it will be useful, but without any warranty. It is provided "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. should the program prove defective, the GMR group does not assume the cost of any necessary servicing, repair or correction. -Download the png in `urdf/roads/dae/png` from shared drive space `LaboratoriIRI/Projects/ADC/simulator/roads/*.png` +In no event unless required by applicable law the author will be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if the author has been advised of the possibility of such damages. -## How to use it +You should have received a copy of the GNU Lesser General Public License +along with this program. If not, see <http://www.gnu.org/licenses/> -`roslaunch road_description spawn_road.launch rviz:=true` diff --git a/docs/images/ppi_conv.gif b/docs/images/ppi_conv.gif new file mode 100644 index 0000000000000000000000000000000000000000..8c05d9fa1a69fd4dfe20a761e686fa035b88493b Binary files /dev/null and b/docs/images/ppi_conv.gif differ