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
| - The `sun` entity exists at the origin of its own coordinate system | ||
| - The `sun/planet` transform places the planet 6 units along x away from the sun | ||
| - The `sun/planet/moon` transform places the moon 3 units along x away from the planet | ||
|
|
There was a problem hiding this comment.
link more detailed snippets!
… of view coordinates
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.
| <!-- Figma file for diagrams in this article: https://www.figma.com/board/PTwJKgi9kQOqG7ZgzdhrDL/Transforms-doc-page-graphs?t=fWkOGxxn6mZkkCON-1 --> | ||
|
|
||
| Rerun comes with built-in support for modeling spatial relationships between entities. | ||
| This page details how the [different archetypes](https://rerun.io/docs/reference/types/archetypes#transforms) involved interact with each other and explains how geometric transforms are set up in Rerun. |
There was a problem hiding this comment.
Nit
| This page details how the [different archetypes](https://rerun.io/docs/reference/types/archetypes#transforms) involved interact with each other and explains how geometric transforms are set up in Rerun. | |
| This page details how the [different archetypes](https://rerun.io/docs/reference/types/archetypes#transforms) involved interact with each other and explains how transforms are set up in Rerun. |
|
|
||
| The [`Transform3D`](https://rerun.io/docs/reference/types/archetypes/transform3d) archetype allows you to specify how one coordinate system relates to another through translation, rotation, and scaling. | ||
|
|
||
| The simplest way to use transforms is through entity path hierarchies, where each transform describes the relationship between an entity and its parent path. |
There was a problem hiding this comment.
NIT: Link to entity path details?
| The [`Transform3D`](https://rerun.io/docs/reference/types/archetypes/transform3d) archetype allows you to specify how one coordinate system relates to another through translation, rotation, and scaling. | ||
|
|
||
| The simplest way to use transforms is through entity path hierarchies, where each transform describes the relationship between an entity and its parent path. | ||
| Note that by default, all entities are connected via identity transforms (to opt out of that, you have to use named transform frames, more on that later). |
There was a problem hiding this comment.
| Note that by default, all entities are connected via identity transforms (to opt out of that, you have to use named transform frames, more on that later). | |
| Note that by default, all entities are connected via identity transforms. |
|
|
||
| In this hierarchy: | ||
| - The `sun` entity exists at the origin of its own coordinate system | ||
| - The `sun/planet` transform places the planet 6 units along x away from the sun |
There was a problem hiding this comment.
| - The `sun/planet` transform places the planet 6 units along x away from the sun | |
| - The `sun/planet` transform places the planet 6 units from the sun, along the x-axis |
6 units along x away was just a weird phrase to parse in my head
| In particular for anyone familiar with ROS we recommend using named transform frames as it allows you to model | ||
| your data much closer to how it would be defined when using ROS' [tf2](https://wiki.ros.org/tf2) library. | ||
|
|
||
| In a nutshell, by explicitly specifying transform frames, you can decouple the spatial relationships from the entity hierarchy. |
There was a problem hiding this comment.
| In a nutshell, by explicitly specifying transform frames, you can decouple the spatial relationships from the entity hierarchy. | |
| By explicitly specifying transform frames, you can decouple spatial relationships from the entity hierarchy. |
|
|
||
| ## Pose transforms | ||
|
|
||
| [`InstancePoses3D`](https://rerun.io/docs/reference/types/archetypes/instance_poses3d) defines geometric poses relative to an entity's transform frame. |
There was a problem hiding this comment.
Typo on instance pose pag max3x3 should be mat3x3
| The simplest way to use transforms is through entity path hierarchies, where each transform describes the relationship between an entity and its parent path. | ||
| Note that by default, all entities are connected via identity transforms (to opt out of that, you have to use named transform frames, more on that later). | ||
|
|
||
| snippet: concepts/transform3d_hierarchy_simple |
There was a problem hiding this comment.
Ooof, this initially rendered as the moon inside my planet. I reset my view and it was fixed. However, it appears to default to wireframe instead of solid?
| 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.
| 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.
| --- | ||
|
|
||
| <!-- Figma file for diagrams in this article: https://www.figma.com/board/PTwJKgi9kQOqG7ZgzdhrDL/Transforms-doc-page-graphs?t=fWkOGxxn6mZkkCON-1 --> | ||
|
|
There was a problem hiding this comment.
Note on overall layout. Right now it feels a little weird so maybe just rearranging the header hierarchy will help?
Maybe something like (no opinion on exact names):
- Transforms
- Entity path transforms
- Named transforms
- Transforms - under the hood
- Special Transform Archetypes
- Pinhole
- View coordinates
- Pose transforms
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.
Draft todo: