Update docs to clarify what data is returned in a frame from the camera

[greenbreakfast]

When looking at the documentation right now, it's hard to figure out what data is returned when reading a frame from the camera. This makes it really hard for users to write their own programs using this library.

With the current documentation, the user must trace through the source code to get some understanding - this is a large barrier to entry. And even then, there's no indication how the frame data is arranged in the members of the Frame object.

The documentation should be updated to:

• Make it clear what data is returned when reading a frame from the camera
• Make it clear the TauLidarCamera library depends on the TauLidarCommon library and give a brief explanation of how
• Offer guidance on the pros and cons of each read frame function, give an idea when each is appropriate
• Explain how the frame data is arranged in each Frame object member
• (Bonus) Offer pointers on how to manipulate the frame data depending on what the user wants to do

@vsemi let's brainstorm on how we can improve the documentation to better cover the above topics

[vsemi]

@greenbreakfast should we do this in the separate common module, or just simply adding in the existing camera module docs (adding description into the readFrame method of Camera)?

[vsemi]

@greenbreakfast could you please have a look if the docs reads better? specifically the Camera and the Frame in common module.

[greenbreakfast]

@vsemi This is a good start. A few more suggestions:

• The function descriptions should explain to the users 1) a brief synopsis of what the function does, 2) what the input parameters are, 3) what the function outputs, and 4) perhaps a usage example. Other details like what to do with the output or comparing this against other functions is better suited in a quickstart or user guide as opposed to the API reference. Specifically:
  • In the description of camera.readFrame it goes into quite a bit of detail on how to increase the frame rate by using readFrameRawData and composing the frame in a different thread. This is useful advice but it doesn't directly relate to the camera.readFrame function. It would probably be better suited in the quickstart/user guide under a "Improving Frame-Rate" header
  • In camera.readFrame and in frame, I definitely see the benefit of showing examples of how to convert to an OpenCV Mat object, but again, this would be better suited in the quickstart/user guide.
• In the frame documentation, we should make it explicit how each array is organized, like does the data go R-G-B or B-G-R or G-R-B. We see the confusion that not knowing the byte ordering can cause in #9
• The camera.setRange description should be updated to accurately describe what the function does and what the two parameters control. Right now it's not clear to a user how to use this function.
  • Another thing, does this need to be done after the camera is opened? If so, we should note this.