RobotLocomotion / drake

Model-based design and verification for robotics.
https://drake.mit.edu
Other
3.35k stars 1.27k forks source link

No documentation for setting the RenderLabel? #16153

Open RussTedrake opened 2 years ago

RussTedrake commented 2 years ago

I looked through the handful of open issues on geometry documentation, but didn't see one that covers this.

https://drake.mit.edu/doxygen_cxx/classdrake_1_1geometry_1_1render_1_1_render_label.html clearly says "it is the user's responsibility to assign labels in a manner that is meaningful for their application". But I couldn't find any documentation anywhere, even searching the c++, that shows how to do it. It wasn't til I searched the source that I found, e.g.:

    PerceptionProperties perception;
    perception.AddProperty("phong", "diffuse", Rgba{0.9, 0.1, 0, 1.0});
    perception.AddProperty("label", "id", RenderLabel(body.index()));
    scene_graph->AssignRole(source_id_, id, perception);

I think that many geometry properties are effectively undocumented and undiscoverable? This might eventually be resolved with #13688. But in the short/immediate term, can we at least add a bread-crumb to the RenderLabel documentation?

jwnimmer-tri commented 4 months ago

The tutorial for rendering_multibody_plant.ipynb has good examples. Adding a link from the RenderLabel class overview docs to the tutorial is probably all we need. (Slightly tricky given #21588; we'll need to link to the landing page or something, and tell people which name to click.)