[mediacapture-depth] From quantized depth to depth measurement in mm; need a convenience function?

anssiko has just created a new issue for 
https://github.com/w3c/mediacapture-depth:

== From quantized depth to depth measurement in mm; need a convenience
 function? ==
Currently, web developers are expected to do some math themselves (see
 below) to convert the quantized depth value they get from the API to 
the actual depth measurement in millimeter units that tell the 
distance from the camera to the object at that particular point.

I'm asking for feedback whether we should:

* **Option 1**: provide a convenience function that takes a quantized 
depth value d<sub>8bit</sub> and returns the corresponding depth 
measurement d in millimeters, or

* **Option 2**: add a non-normative section that gives explicit 
guidance to web developers how they should do this conversion 
themselves, along with some practical examples.

This is what web developers are currently expected to do (option 2):

The depth measurement d (in millimeter units) is recovered by solving 
the [depth to grayscale conversion][1] for d as follows:

* If the depth to grayscale conversion is `linear`, given 
d<sub>8bit</sub>, near and far, we first normalize d<sub>8bit</sub> to
 [0, 1] range:

![normalize]

... and then solve the [rules to convert using range linear][2] for d:

![depth_from_linear]

* If the depth to grayscale conversion is `inverse`, given 
d<sub>8bit</sub>, near and far, we similarly first normalize 
d<sub>8bit</sub> to [0, 1] range:

![normalize]

... and then solve the [rules to convert using range inverse][3] for 
d:

![depth_from_inverse]

This translates into a couple of lines of boilerplate JavaScript code,
 that I assume, will be rolled into a JS library as usual at some 
point. I think I'm leaning toward option 2 for v1 at least, but wanted
 to loop you in before baking this into the spec.

(As a recap, the reason why we have two ways to do the depth to 
grayscale conversion is that `inverse` allocates more bits to the near
 depth values and fewer bits to the far values (think GPU z-buffer), 
more appropriate if the source depth map bit depth is greater than 8, 
while `linear` allocates the bits evenly, better to be used if the 
source depth map bit depth is 8 or less.)

[1]: 
https://w3c.github.io/mediacapture-depth/#dfn-convert-the-depth-map-value-to-grayscale
[2]: 
https://w3c.github.io/mediacapture-depth/#dfn-rules-to-convert-using-range-linear
[3]: 
https://w3c.github.io/mediacapture-depth/#dfn-rules-to-convert-using-range-inverse
[normalize]: 
https://cloud.githubusercontent.com/assets/765510/13952822/50b690b8-f041-11e5-8e82-c776ad7263f8.png
[depth_from_linear]: 
https://cloud.githubusercontent.com/assets/765510/13952828/5620edaa-f041-11e5-9193-5334b540b334.png
[depth_from_inverse]: 
https://cloud.githubusercontent.com/assets/765510/13952851/8a3bafb2-f041-11e5-8202-5df00feba746.png

Please view or discuss this issue at 
https://github.com/w3c/mediacapture-depth/issues/112 using your GitHub
 account

Received on Tuesday, 22 March 2016 13:55:47 UTC