Merge pull request #197 from Unity-Technologies/dev

Version 0.6.0

.github/workflows/pre-commit.yml

@@ -13,5 +13,6 @@ jobs:
                   python-version: 3.7.x
             - uses: actions/setup-dotnet@v1
               with:
-                  dotnet-version: '3.1.x'
+                  dotnet-version: '6.0.x'
+                  include-prerelease: true
             - uses: pre-commit/action@v2.0.0

.github/workflows/stale.yaml

@@ -0,0 +1,27 @@
+name: 'Stale issue handler'
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 17 * * *' # 17:00 UTC; 10:00 PDT
+
+permissions:
+  issues: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v4.0.0
+        id: stale
+        with:
+          stale-issue-label: 'stale'
+          stale-issue-message: 'This issue has been marked stale because it has been open for 14 days with no activity. Please remove the stale label or comment on this issue, or the issue will be automatically closed in the next 14 days.'
+          days-before-stale: 14
+          days-before-pr-stale: -1
+          days-before-close: 14
+          days-before-pr-close: -1
+          exempt-issue-labels: 'blocked,must,should,keep,pinned,work-in-progress,request,announcement'
+          close-issue-message: 'This issue has been marked stale for 14 days and will now be closed. If this issue is still valid, please ping a maintainer.'
+      - name: Print outputs
+        run: echo ${{ join(steps.stale.outputs.*, ',') }}
+

.pre-commit-config.yaml

@@ -25,7 +25,8 @@ repos:
 
 
 - repo: https://github.com/dotnet/format
-  rev: "7e343070a0355c86f72bdee226b5e19ffcbac931"
+  rev: v5.1.225507
   hooks:
       - id: dotnet-format
+        entry: dotnet-format whitespace
         args: [--folder, --include]

.yamato/yamato-config.yml

@@ -1,7 +1,7 @@
 name: Connector Unit Tests
 agent:
     type: Unity::VM
-    image: robotics/ci-ubuntu20:latest
+    image: robotics/ci-ubuntu20:v0.1.0-795910
     flavor: i1.large
 variables:
     PATH: /root/.local/bin:/home/bokken/bin:/home/bokken/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/sbin:/home/bokken/.npm-global/bin

CONTRIBUTING.md

@@ -30,8 +30,20 @@ does the following:
 - Has corresponding changes to documentation, unit tests and sample environments (if
   applicable)
 - Contains a summary of the tests performed to validate your changes
+- Updates the [Changelog](com.unity.robotics.ros-tcp-connector/CHANGELOG.md) and describes changes in the Unreleased section
 - Links to issue numbers that the PR resolves (if any)
 
+## Workflow
+
+This project is provided as a package to be imported into a Unity project. In order to avoid common issues regarding version control and unmanaged files, the suggested workflow for contributing to the package is as follows:
+
+1. Clone this repository to a known location on your local machine (e.g. Documents).
+2. Git checkout the `dev` branch to ensure you have the latest staged changes.
+3. In a development Unity project (e.g. a new project created from the Unity Hub of the minimum Unity [version](README.md) or above), open the `Window > Package Manager`.
+4. Click the `+` in the top-left of the Package Manager window and select `Add package from disk...`.
+5. Navigate to the cloned repository, and select the `com.unity.<package>/package.json` file. Click `Open`.
+6. The local version of the package is now added to your Unity project! Changes made to your cloned directory will update in your Unity project.
+
 <!-- ## Continuous Integration (CI)
 
 We run continuous integration on all PRs; all tests must be passing before the PR is merged. -->
@@ -41,13 +53,10 @@ We run continuous integration on all PRs; all tests must be passing before the P
 All Python code should follow the [PEP 8 style guidelines](https://pep8.org/).
 
 All C# code should follow the [Microsoft C# Coding Conventions](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions).
-Additionally, the [Unity Coding package](https://docs.unity3d.com/Packages/com.unity.coding@0.1/manual/index.html)
-can be used to format, encode, and lint your code according to the standard Unity
-development conventions. Be aware that these Unity conventions will supersede the
-Microsoft C# Coding Conventions where applicable.
+(Code may be reformatted to Unity coding standards where applicable.)
 
-Please note that even if the code you are changing does not adhere to these guidelines,
-we expect your submissions to follow these conventions.
+Please note that even if the code you are changing does not follow these conventions,
+we expect your submissions to do so.
 
 ## Contributor License Agreements
 

README.md

@@ -1,4 +1,4 @@
-# ROS-TCP-Connector
+# ROS TCP Connector
 
 [![Version](https://img.shields.io/github/v/tag/Unity-Technologies/ROS-TCP-Connector)](https://github.com/Unity-Technologies/ROS-TCP-Connector/releases)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE.md)
@@ -7,24 +7,37 @@
 ![ROS](https://img.shields.io/badge/ros2-foxy-brightgreen)
 ![Unity](https://img.shields.io/badge/unity-2020.2+-brightgreen)
 
+## Introduction
+
+This repository contains two Unity packages: the ROS TCP Connector, for sending/receiving messages from ROS, and the Visualizations Package, for adding visualizations of incoming and outgoing messages in the Unity scene.
+
 ## Installation
-1. Using Unity 2020.2 or later, open the package manager from `Window` -> `Package Manager` and select "Add package from git URL..."
-![image](https://user-images.githubusercontent.com/29758400/110989310-8ea36180-8326-11eb-8318-f67ee200a23d.png)
-2. Enter the following URL. If you don't want to use the latest version, substitute your desired version tag where we've put `v0.5.0` in this example:
-`https://github.com/Unity-Technologies/ROS-TCP-Connector.git?path=/com.unity.robotics.ros-tcp-connector#v0.5.0`
-3. Click `Add`.
+1. Using Unity 2020.2 or later, open the Package Manager from `Window` -> `Package Manager`.
+2. In the Package Manager window, find and click the + button in the upper lefthand corner of the window. Select `Add package from git URL....`
+
+    ![image](https://user-images.githubusercontent.com/29758400/110989310-8ea36180-8326-11eb-8318-f67ee200a23d.png)
 
+3. Enter the git URL for the desired package. Note: you can append a version tag to the end of the git url, like `#v0.4.0` or `#v0.5.0`, to declare a specific package version, or exclude the tag to get the latest from the package's `main` branch.
+    1. For the ROS-TCP-Connector, enter `https://github.com/Unity-Technologies/ROS-TCP-Connector.git?path=/com.unity.robotics.ros-tcp-connector`.
+    2. For Visualizations, enter `https://github.com/Unity-Technologies/ROS-TCP-Connector.git?path=/com.unity.robotics.visualizations`.
+4. Click `Add`.
+
+To install from a local clone of the repository, see [installing a local package](https://docs.unity3d.com/Manual/upm-ui-local.html) in the Unity manual.
 
 ## Tutorials
-Scripts used to send [ROS](https://www.ros.org/) messages to an [TCP endpoint](https://github.com/Unity-Technologies/ROS_TCP_Endpoint) running as a ROS node.
+<!-- Scripts used to send [ROS](https://www.ros.org/) messages to an [TCP endpoint](https://github.com/Unity-Technologies/ROS_TCP_Endpoint) running as a ROS node. -->
+
+This Unity package provides four main features:
 
-This Unity package provides three main features:
+- ROSConnection: A component that sets up communication between ROS and Unity. See the [Unity Robotics Hub](https://github.com/Unity-Technologies/Unity-Robotics-Hub/blob/main/tutorials/ros_unity_integration/README.md) for information and tutorials.
 
-- ROSConnection: See the [Unity Robotics Hub](https://github.com/Unity-Technologies/Unity-Robotics-Hub/blob/main/tutorials/ros_unity_integration/README.md) repository for information and tutorials on how to use this component.
+- [Message Generation](MessageGeneration.md): A tool to generate C# classes for ROS message types.
 
-- [Message Generation](MessageGeneration.md)
+- Visualizations: A suite of default configurations and APIs to visualize incoming and outgoing information from ROS.
+    - See the [Nav2 SLAM Example](https://github.com/Unity-Technologies/Robotics-Nav2-SLAM-Example) for tutorials on using the Visualizations Package!
+    - You can also view the package's [Usage Information](com.unity.robotics.visualizations/Documentation~/README.md) for more details on using the package in your own project.
 
-- [ROSGeometry](ROSGeometry.md)
+- [ROSGeometry](ROSGeometry.md): A set of extensions that convert geometries between Unity and other coordinate frames.
 
 ## ROS#
 

ROSGeometry.md

@@ -2,12 +2,56 @@
 
 In Unity, the X axis points right, Y up, and Z forward. ROS, on the other hand, supports various coordinate frames: in the most commonly-used one, X points forward, Y left, and Z up. In ROS terminology, this frame is called "FLU" (forward, left, up), whereas the Unity coordinate frame would be "RUF" (right, up, forward).
 
-The ROSGeometry namespace contains code to make it easier to work with these various coordinate frames - letting you be explicit about what coordinates a given value is in at compile time, and managing the conversions for you. It does this with two generic structs, `Vector3<C>` and `Quaternion<C>`. The type parameter C indicates the coordinate frame you're working in - either FLU, or RUF, or perhaps a more exotic frame such as NED (north, east, down) or ENU (east, north, up), commonly used in aviation.
+The ROSGeometry namespace contains code to make it easier to work with these various coordinate frames - letting you be explicit about what coordinates a given value is in at compile time, and managing the conversions for you.
 
+Here's the using declaration for adding ROSGeometry to your namespace:
+
+    using Unity.Robotics.ROSTCPConnector.ROSGeometry;
+
+# Ros Message conversions:
+
+The main ROS position messages (geometry_msgs/Point, geometry_msgs/Point32 and geometry_msgs/Vector3) can be converted to and from Unity Vector3s like this:
+
+	PointMsg ToRosExample(Vector3 position)
+	{
+		return position.To<FLU>();
+	}
+
+	Vector3 ToUnityExample(PointMsg message)
+	{
+		return message.From<FLU>();
+	}
+
+Similarly, the geometry_msgs/Quaternion message can be converted to and from a Unity Quaternion.
+
+	QuaternionMsg myRosQuaternion = myGameObject.transform.rotation.To<FLU>();
+	Quaternion myUnityQuaternion = myRosQuaternion.From<FLU>();
+
+Hence, writing 3d data into a message can often be as simple as writing:
+
+	ImuMsg msg = new ImuMsg()
+	{
+		linear_acceleration = acceleration.To<FLU>();
+		orientation = rigidbody.transform.rotation.To<FLU>();
+		angular_velocity = rigidbody.angularVelocity.To<FLU>();
+	}
+	ros.Send("imu", msg);
+
+Unity's standard Transform class also has a `To<C>()` extension method that returns a ROS Transform message. So creating a geometry_msgs/Transform message typically looks like this:
+
+    TransformMsg msg = myGameObject.transform.To<FLU>());
+
+# Internal details
+
+Some more detail about what's going on here: The core of the ROSGeometry package is the two generic structs, `Vector3<C>` and `Quaternion<C>`. The type parameter C here indicates the coordinate frame you're working in - either FLU, or RUF, or perhaps one of the more exotic frames such as NED (north, east, down) or ENU (east, north, up), used in aviation.
+
+These are fully-fledged Vector3 and Quaternion classes, so if you want, you can work with them directly to perform geometric operations in an arbitrary coordinate space. (Note, it's a compile time error to add a Vector3<FLU> to a Vector3<RUF>.)
+
+These are the types returned by the `To<FLU>()` calls above. Vector3<C> also has implicit conversions to MPoint, MPoint32, and MVector3, which is how this one call can be used to convert to all three data types.
 
 # Converting between frames:
 
-For example, if you need to convert an object's position into the FLU coordinate frame, you might write:
+If, for example, you need to convert an object's position into the FLU coordinate frame, you might explicitly create a Vector3<FLU> like this:
 
     Vector3<FLU> rosPos = obj.transform.position.To<FLU>();
 
@@ -20,7 +64,7 @@ To convert back, just access the "toUnity" property on the vector.
 
     Vector3 unityPos = rosPos.toUnity;
 
-And the same functions apply for converting Quaternions.
+The same functions and properties apply for converting Quaternions.
 
 # Ros Message conversions:
 
@@ -40,17 +84,17 @@ Unity's standard Transform class also has a `To<C>()` extension method that retu
 
 # Converting incoming messages
 
-You can also convert Points, Point32s and Vector3s back into Unity coordinates. To convert a Point in coordinate space C directly into a Unity Vector3, you can write `From<C>`. For example:
+You can also convert Points, Point32s and Vector3s back into Unity coordinates. If you know that a Point is in coordinate space C, you can convert it into a Unity Vector3 in the unity coordinate space by writing `From<C>`. For example:
 
     void SubscriberCallback(Point p)
 	{
 	  transform.position = p.From<FLU>();
 	}
 
-Or, if you need to work with them in the FLU coordinate space for now, you can write:
+Or, if you need to work with it in the FLU coordinate space for now, you can write:
 
     Vector3<FLU> rosPos = p.As<FLU>();
 
-(Note that this does NOT do any coordinate conversion. It simply assumes the point is in the FLU coordinate frame already, and transfers it into an appropriate container.)
+(Note, the As function does NOT do any coordinate conversion. It simply assumes the point is in the FLU coordinate frame already, and transfers it into an appropriate container.)
 
 And again, the same goes for converting a Quaternion message into a Unity Quaternion or `Quaternion<C>`.

TestRosTcpConnector/Packages/manifest.json

@@ -1,15 +1,16 @@
 {
   "dependencies": {
-    "com.unity.collab-proxy": "1.3.9",
+    "com.unity.collab-proxy": "1.5.7",
     "com.unity.ide.rider": "2.0.7",
-    "com.unity.ide.visualstudio": "2.0.3",
-    "com.unity.ide.vscode": "1.2.2",
-    "com.unity.render-pipelines.universal": "10.0.0-preview.26",
+    "com.unity.ide.visualstudio": "2.0.8",
+    "com.unity.ide.vscode": "1.2.3",
+    "com.unity.render-pipelines.universal": "10.2.2",
     "com.unity.robotics.ros-tcp-connector": "file:../../com.unity.robotics.ros-tcp-connector",
-    "com.unity.test-framework": "1.1.20",
+    "com.unity.test-framework": "1.1.24",
     "com.unity.testtools.codecoverage": "1.0.0",
     "com.unity.textmeshpro": "3.0.1",
-    "com.unity.timeline": "1.4.3",
+    "com.unity.timeline": "1.4.8",
+    "com.unity.toolchain.macos-x86_64-linux-x86_64": "0.1.21-preview",
     "com.unity.ugui": "1.0.0",
     "com.unity.modules.ai": "1.0.0",
     "com.unity.modules.androidjni": "1.0.0",