camera - Is Android's CameraInfo.orientation correctly documented? Incorrectly implemented?

Question

In Android you can get a description of the properties of a Camera by retrieving a CameraInfo. I'm interested in orientation, as described at http://developer.android.com/reference/android/hardware/Camera.CameraInfo.html#orientation

However the documentation seems inconsistent with how all four of my devices behave, and, I have news of a fifth device for which this seemly fixed value changes.

In particular, the documentation says:

The value is the angle that the camera image needs to be rotated clockwise so it shows correctly on the display in its natural orientation. ... For example, suppose a device has a naturally tall screen. The back-facing camera sensor is mounted in landscape. You are looking at the screen. If the top side of the camera sensor is aligned with the right edge of the screen in natural orientation, the value should be 90. If the top side of a front-facing camera sensor is aligned with the right of the screen, the value should be 270.

But in the stated example, it is the camera image that is rotated 90 degrees clockwise relative to the naturally tall orientation, not the other way around. That is, the image, whose top is aligned with the right hand side of the device, needs 270 degrees clockwise rotation to align with the device's top side.

At least, all four of my devices report "90" for this value, and all act as if the camera's top is the right side of the device when held in natural orientation. That is, the image must be rotated 270 degrees clockwise, not 90, to match the natural orientation. The example seems correct; the first line does not.

This example code seems to support my conclusion as it only gives the right result when orientation is interpreted as above.

Strangely, I have log evidence from one user's device that shows it reporting this value as 90 at times, and 0 at other times! It ought to be a physical property of how the camera is seated in the device, right?

1. Can anyone confirm that the first line of the documentation is in fact wrong, and the example is right?
2. Has anyone observed a changing value of CameraInfo.orientation? Is there evidence in docs that this is legal behavior, or is it likely a bug in the device?
3. Any other related comments, experiences, gotchas I have not run into yet?

Answer 1

I believe I've answered my own question here after some more thinking.

The example is correct. And, the text is correct actually. In the given example, if the preview data is displayed on the screen, it will appear rotated 90 degrees counter-clockwise, since "up" in the data is at the display's right hand, and it is shown on the display, whose "up" is at the data's left hand so to speak. So, it would be necessary to compensate by rotating the image data 90 degrees clockwise before displaying.

I think it's more natural to understand this figure as the rotation at which the camera is mounted relative to the natural orientation.

For this reasons and others I've concluded that the device that shows a changing value for orientation is simply buggy. At the least, when it reports 0, its data is acting like "90" is the right value.