prosilica_camera/Reviews/2010-01-21 Doc Review

Reviewer:

• Jeremy Leibs

Instructions for doing a doc review

See DocReviewProcess for more instructions

1. Does the documentation define the Users of your Package, i.e. for the expected usages of your Stack, which APIs will users engage with?
2. Are all of these APIs documented?
3. Do relevant usages have associated tutorials? (you can ignore this if a Stack-level tutorial covers the relevant usage), and are the indexed in the right places?
4. If there are hardware dependencies of the Package, are these documented?
5. Is it clear to an outside user what the roadmap is for the Package?
6. Is it clear to an outside user what the stability is for the Package?
7. Are concepts introduced by the Package well illustrated?
8. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
9. Are any mathematical formulas in the Package not covered by papers properly documented?

Jeremy

1. Does the documentation define the Users of your Package, i.e. for the expected usages of your Stack, which APIs will users engage with?
   • Pretty clear: anyone that needs access to the Prosilica.
2. Are all of these APIs documented?

   • If the polled_camera API is unstable, this should probably be mentioned on the prosilica_camera page.

   • Should mention that image_transport is being used on all the image topics since this extends the API.

   • I would hide the read/write memory descriptions on a separate page, such as: prosilica_camera/Advanced

3. Do relevant usages have associated tutorials? (you can ignore this if a Stack-level tutorial covers the relevant usage), and are the indexed in the right places?

   • The prosilica_camera/Tutorials/ProsilicaGigECameraIntroduction tutorial would probably be better served by additioanlly hooking up an image-viewer to a topic before making the polled service call.

     • A code-snippet making the service call and doing something with the image would be even better.

     • Such a tutorial could probably live off of the polled_camera page and ought to simply work with the prosilica.

4. If there are hardware dependencies of the Package, are these documented?
   • Prosilica Gig-E cameras.
5. Is it clear to an outside user what the roadmap is for the Package?
   • Needs a short roadmap/stablity section.
6. Is it clear to an outside user what the stability is for the Package?
   • Needs a short roadmap/stablity section.
7. Are concepts introduced by the Package well illustrated?

   • This probably isn't necessary in and of itself. I would include an appropriate link to the image_pipeline.

8. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
   • N/A
9. Are any mathematical formulas in the Package not covered by papers properly documented?
   • N/A

For each launch file in a Package

1. Is it clear how to run that launch file?

   • Was not clear to me how to use prosilica.launch. Is there some kind of polled_image_view somewhere?

     • Playing around a little, I subscribed with image:=prosilica/my_polled/image_raw and then invoked the service call:

       • rosservice call prosilica/request_image my_polled '{x_offset: 0, y_offset: 0, height: 100, width: 100}'

   • freerun.launch seemed to do what I expected

2. Does the launch file start up with no errors when run correctly?

   • I get a WARN: Failed to load intrinsics from camera which is not documented in the troubleshooting.

3. Do the Nodes in that launch file correctly use ROS_ERROR/ROS_WARN/ROS_INFO logging levels?
   • Yes

Concerns / issues

• Jeremy: See above comments for details:

  • Roadmap/stablity section.

  • Improve prosilica_camera/Tutorials/ProsilicaGigECameraIntroduction to at least hook up an image viewer, though a full code-snippet would be preferable.

  • Document WARN: Failed to load intrinsics from camera in Troubleshooting.

  • Hide read-write API

  • Mention that the polled_camera API is unstable.

  • Mention and link to image_transport somewhere

Conclusion