Complete overhaul of transform manual page #12034
Conversation
Wumpf
added
📖 documentation
|
Latest documentation preview deployed successfully.
Note: This comment is updated whenever you push a commit. |
Wumpf
force-pushed
the
andreas/tf/doc-refresh
branch
from
ea70445 to
58c07bc
Compare
|
Web viewer built successfully.
View image diff on kitdiff. Note: This comment is updated whenever you push a commit. |
Wumpf
force-pushed
the
andreas/tf/new-pinhole-bp-example
branch
from
e77d1e3 to
2b26a70
Compare
Wumpf
force-pushed
the
andreas/tf/doc-refresh
branch
from
270fe8c to
86a9bcd
Compare
ntjohnson1
left a comment
ntjohnson1
left a comment
There was a problem hiding this comment.
Overall I think this looks good. I'd consider all my notes to basically be nits. The organization of headers to make the flow clearer is probably the biggest thing.
Leaving as a comment since this is still a draft and I assume you want a final pass after check boxes are completed.
| Note that unlike in ROS, you can log your transform relationship on _any_ entity. | ||
| However, currently once an entity specified the relation between two frames, this relation may no longer be logged on any other entity. | ||
|
|
||
| Named transform frames have several advantages over entity path based hierarchies: |
There was a problem hiding this comment.
The nicest part for me running the snippets was that I could hide the sun when using names but maybe that is captured with the decoupling entities from transforms already.
There was a problem hiding this comment.
hmmm interesting. I'd lean towards it already being covered since with enough clicks you can also have it. But good point 🤔
| Example: | ||
| TODO: xlanguage please. | ||
| ```python | ||
| rr.log("robot", rr.Transform3D(translation=[1, 0, 0])) |
There was a problem hiding this comment.
These little code snippets didn't display anything interesting but made the idea concrete. Maybe the TODO will resolve that.
There was a problem hiding this comment.
as per above comment I'm leaving them as-is now since they're more nieche and getting runnable xlanguage snippets up is always a bit of a hassle
… of view coordinates
Wumpf
force-pushed
the
andreas/tf/doc-refresh
branch
from
86a9bcd to
671717a
Compare
|
|
||
| Given these entities: | ||
| TODO: xlanguage please | ||
| ```python |
There was a problem hiding this comment.
decided to keep these entities single language. it's a lot of effort translating them and making them strictly runnable. As pointed out they also don't look particularly good atm
So rather than spending more time on it I leave it as this is an advanced topic anyways
MichaelGrupp
left a comment
MichaelGrupp
left a comment
There was a problem hiding this comment.
Mostly small wording suggestions. Nice documentation!
| ### Named transform frames | ||
|
|
||
| While entity path hierarchies work well for many cases, sometimes you need more flexibility in organizing your transforms. | ||
| In particular for anyone familiar with ROS we recommend using named transform frames as it allows you to model |
There was a problem hiding this comment.
Grammar nit: missing commas between clauses
| In particular for anyone familiar with ROS we recommend using named transform frames as it allows you to model | |
| In particular, for anyone familiar with ROS, we recommend using named transform frames, as it allows you to model |
| The relationship between transform frames is then determined by logging [`Transform3D`](https://rerun.io/docs/reference/types/archetypes/transform3d) | ||
| with `child_frame` and `parent_frame` parameters to define the geometric relationship between two transform frames. |
There was a problem hiding this comment.
| The relationship between transform frames is then determined by logging [`Transform3D`](https://rerun.io/docs/reference/types/archetypes/transform3d) | |
| with `child_frame` and `parent_frame` parameters to define the geometric relationship between two transform frames. | |
| The geometric relationship between two transform frames is then determined by logging [`Transform3D`](https://rerun.io/docs/reference/types/archetypes/transform3d) | |
| with `child_frame` and `parent_frame` parameters set to their respective names. |
| snippet: concepts/transform3d_hierarchy_named_frames | ||
|
|
||
| Note that unlike in ROS, you can log your transform relationship on _any_ entity. | ||
| However, currently once a relation between two frames has been logged to an entity, this relation may no longer be logged on any other entity. |
There was a problem hiding this comment.
Would highlight / explain this a bit different, e.g.:
| However, currently once a relation between two frames has been logged to an entity, this relation may no longer be logged on any other entity. | |
| **Note:** A current limitation to this is that once a `Transform3D` relating two frames has been logged to an entity, this particular relation may no longer be logged on any other entity. |
|
|
||
| Named transform frames have several advantages over entity path based hierarchies: | ||
| * topology may change over time | ||
| * which entity is associated with which frame may change over time (it can also be [overridden via blueprint](../concepts/visualizers-and-overrides.md)) |
There was a problem hiding this comment.
I know, "explicit" is not the favored wording anymore, but here I think it could be good 😛
| * which entity is associated with which frame may change over time (it can also be [overridden via blueprint](../concepts/visualizers-and-overrides.md)) | |
| * the association of entities with coordinate frames is explicit and can also be changed over time (it can also be [overridden via blueprint](../concepts/visualizers-and-overrides.md)) |
| * 3D in 2D: if the pinhole is at the origin of the view, 3D objects can be projected through pinhole camera into the view. | ||
| * Both the [nuscenes](https://rerun.io/examples/robotics/nuscenes_dataset) and [arkit](https://rerun.io/examples/spatial-computing/arkit_scenes) examples make use of this | ||
|
|
||
| If a transform frame relationship has both a pinhole projection & regular transforms (in this context often regarded as the camera extrinsics) |
There was a problem hiding this comment.
missing comma
| If a transform frame relationship has both a pinhole projection & regular transforms (in this context often regarded as the camera extrinsics) | |
| If a transform frame relationship has both a pinhole projection & regular transforms (in this context often regarded as the camera extrinsics), |
| [Pinholes](https://rerun.io/docs/reference/types/archetypes/view_coordinates) have a view coordinates field integrated as a shortcut. | ||
| The default coordinate system for pinhole entities is `RDF` (X=Right, Y=Down, Z=Forward). | ||
|
|
||
| WARNING: unlike in 3D views where `rr.ViewCoordinates` only impacts how the rendered scene is oriented, applying `rr.ViewCoordinates` to a pinhole-camera will actually influence the projection transform chain. Under the hood this value inserts a hidden transform that re-orients the axis of projection. Different world-content will be projected into your camera with different orientations depending on how you choose this value. See for instance the [`open_photogrammetry_format`](https://rerun.io/examples/3d-reconstruction/open_photogrammetry_format) example. |
There was a problem hiding this comment.
I think this type of warning block would be more consistent with the rest of the docs (example: https://rerun.io/docs/howto/logging/send-columns)
| WARNING: unlike in 3D views where `rr.ViewCoordinates` only impacts how the rendered scene is oriented, applying `rr.ViewCoordinates` to a pinhole-camera will actually influence the projection transform chain. Under the hood this value inserts a hidden transform that re-orients the axis of projection. Different world-content will be projected into your camera with different orientations depending on how you choose this value. See for instance the [`open_photogrammetry_format`](https://rerun.io/examples/3d-reconstruction/open_photogrammetry_format) example. | |
| > ⚠️ Unlike in 3D views where `rr.ViewCoordinates` only impacts how the rendered scene is oriented, applying `rr.ViewCoordinates` to a pinhole-camera will actually influence the projection transform chain. Under the hood this value inserts a hidden transform that re-orients the axis of projection. Different world-content will be projected into your camera with different orientations depending on how you choose this value. See for instance the [`open_photogrammetry_format`](https://rerun.io/examples/3d-reconstruction/open_photogrammetry_format) example. |
Related
What
Even without the new addition of named transform frames, the "Transforms & Spaces" page was very outdated.
This rewrites it completely and explains now how all the different kind of transforms work and relate to each other
We'll likely refine this page further in the coming days. So doesn't have to be perfect yet, just better than before.
Preview: https://landing-fg32i37mi-rerun.vercel.app/docs/concepts/transforms