Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Snorm range max #4121

Merged
merged 9 commits into from
Jul 20, 2016
Merged

Snorm range max #4121

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d8c1178
Added rangeMax for specifying different levels of precision for
lasalvavida Jul 14, 2016
920eb39
Added tests
lasalvavida Jul 14, 2016
49f8870
Doc grammar
lasalvavida Jul 14, 2016
89ec94b
Split off into new function and update CHANGES.md
lasalvavida Jul 14, 2016
d905434
Fix a few existing tests
lasalvavida Jul 14, 2016
e8b8e00
Missed CHANGES.md
lasalvavida Jul 14, 2016
8c664d4
rangeMax isn't optional on octEncodeInRange and octDecodeInRange
lasalvavida Jul 14, 2016
332c582
Added doc note about bit size
lasalvavida Jul 15, 2016
fb3a0a7
Should be rangeMax+1
lasalvavida Jul 15, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 17 additions & 10 deletions Source/Core/AttributeCompression.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,14 @@
define([
'./Cartesian2',
'./Cartesian3',
'./defaultValue',
'./defined',
'./DeveloperError',
'./Math'
], function(
Cartesian2,
Cartesian3,
defaultValue,
defined,
DeveloperError,
CesiumMath) {
Expand All @@ -23,21 +25,22 @@ define([
var AttributeCompression = {};

/**
* Encodes a normalized vector into 2 SNORM values in the range of [0-255] following the 'oct' encoding.
* Encodes a normalized vector into 2 SNORM values in the range of [0-rangeMax] following the 'oct' encoding.
*
* Oct encoding is a compact representation of unit length vectors. The encoding and decoding functions are low cost, and represent the normalized vector within 1 degree of error.
* The 'oct' encoding is described in "A Survey of Efficient Representations of Independent Unit Vectors",
* Cigolle et al 2014: {@link http://jcgt.org/published/0003/02/01/}
*
* @param {Cartesian3} vector The normalized vector to be compressed into 2 byte 'oct' encoding.
* @param {Cartesian2} result The 2 byte oct-encoded unit length vector.
* @param {Number} [rangeMax=255] The maximum value of the SNORM range, 255 by default.
* @returns {Cartesian2} The 2 byte oct-encoded unit length vector.
*
* @exception {DeveloperError} vector must be normalized.
*
* @see AttributeCompression.octDecode
*/
AttributeCompression.octEncode = function(vector, result) {
AttributeCompression.octEncode = function(vector, result, rangeMax) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

result parameters should come last so we need to introduce a new function (and we can implement this function using that new one; no need to deprecate this).

//>>includeStart('debug', pragmas.debug);
if (!defined(vector)) {
throw new DeveloperError('vector is required.');
Expand All @@ -50,6 +53,7 @@ define([
throw new DeveloperError('vector must be normalized.');
}
//>>includeEnd('debug');
rangeMax = defaultValue(rangeMax, 255);

result.x = vector.x / (Math.abs(vector.x) + Math.abs(vector.y) + Math.abs(vector.z));
result.y = vector.y / (Math.abs(vector.x) + Math.abs(vector.y) + Math.abs(vector.z));
Expand All @@ -60,8 +64,8 @@ define([
result.y = (1.0 - Math.abs(x)) * CesiumMath.signNotZero(y);
}

result.x = CesiumMath.toSNorm(result.x);
result.y = CesiumMath.toSNorm(result.y);
result.x = CesiumMath.toSNorm(result.x, rangeMax);
result.y = CesiumMath.toSNorm(result.y, rangeMax);

return result;
};
Expand All @@ -72,24 +76,27 @@ define([
* @param {Number} x The x component of the oct-encoded unit length vector.
* @param {Number} y The y component of the oct-encoded unit length vector.
* @param {Cartesian3} result The decoded and normalized vector
* @param {Number} [rangeMax=255] The maximum value of the SNORM range, 255 by default.
* @returns {Cartesian3} The decoded and normalized vector.
*
* @exception {DeveloperError} x and y must be a signed normalized integer between 0 and 255.
* @exception {DeveloperError} x and y must be a signed normalized integer between 0 and rangeMax.
*
* @see AttributeCompression.octEncode
*/
AttributeCompression.octDecode = function(x, y, result) {
AttributeCompression.octDecode = function(x, y, result, rangeMax) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment.

rangeMax = defaultValue(rangeMax, 255);

//>>includeStart('debug', pragmas.debug);
if (!defined(result)) {
throw new DeveloperError('result is required.');
}
if (x < 0 || x > 255 || y < 0 || y > 255) {
throw new DeveloperError('x and y must be a signed normalized integer between 0 and 255');
if (x < 0 || x > rangeMax || y < 0 || y > rangeMax) {
throw new DeveloperError('x and y must be a signed normalized integer between 0 and ' + rangeMax);
}
//>>includeEnd('debug');

result.x = CesiumMath.fromSNorm(x);
result.y = CesiumMath.fromSNorm(y);
result.x = CesiumMath.fromSNorm(x, rangeMax);
result.y = CesiumMath.fromSNorm(y, rangeMax);
result.z = 1.0 - (Math.abs(result.x) + Math.abs(result.y));

if (result.z < 0.0)
Expand Down
18 changes: 11 additions & 7 deletions Source/Core/Math.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,25 +218,29 @@ define([
};

/**
* Converts a scalar value in the range [-1.0, 1.0] to a 8-bit 2's complement number.
* Converts a scalar value in the range [-1.0, 1.0] to an SNORM in the range [0, rangeMax]
* @param {Number} value The scalar value in the range [-1.0, 1.0]
* @returns {Number} The 8-bit 2's complement number, where 0 maps to -1.0 and 255 maps to 1.0.
* @param {Number} [rangeMax=255] The maximum value in the mapped range, 255 by default.
* @returns {Number} An SNORM value, where 0 maps to -1.0 and rangeMax maps to 1.0.
*
* @see CesiumMath.fromSNorm
*/
CesiumMath.toSNorm = function(value) {
return Math.round((CesiumMath.clamp(value, -1.0, 1.0) * 0.5 + 0.5) * 255.0);
CesiumMath.toSNorm = function(value, rangeMax) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update CHANGES.md since this is in the public API.

rangeMax = defaultValue(rangeMax, 255);
return Math.round((CesiumMath.clamp(value, -1.0, 1.0) * 0.5 + 0.5) * rangeMax);
};

/**
* Converts a SNORM value in the range [0, 255] to a scalar in the range [-1.0, 1.0].
* Converts an SNORM value in the range [0, rangeMax] to a scalar in the range [-1.0, 1.0].
* @param {Number} value SNORM value in the range [0, 255]
* @param {Number} [rangeMax=255] The maximum value in the SNORM range, 255 by default.
* @returns {Number} Scalar in the range [-1.0, 1.0].
*
* @see CesiumMath.toSNorm
*/
CesiumMath.fromSNorm = function(value) {
return CesiumMath.clamp(value, 0.0, 255.0) / 255.0 * 2.0 - 1.0;
CesiumMath.fromSNorm = function(value, rangeMax) {
rangeMax = defaultValue(rangeMax, 255);
return CesiumMath.clamp(value, 0.0, rangeMax) / rangeMax * 2.0 - 1.0;
};

/**
Expand Down
71 changes: 71 additions & 0 deletions Specs/Core/AttributeCompressionSpec.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,77 @@ defineSuite([
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result)).toEqualEpsilon(normal, epsilon);
});

it('oct encoding high precision', function() {
var rangeMax = 4294967295;
var epsilon = CesiumMath.EPSILON8;

var encoded = new Cartesian2();
var result = new Cartesian3();
var normal = new Cartesian3(0.0, 0.0, 1.0);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(0.0, 0.0, -1.0);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(0.0, 1.0, 0.0);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(0.0, -1.0, 0.0);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(1.0, 0.0, 0.0);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(-1.0, 0.0, 0.0);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(1.0, 1.0, 1.0);
Cartesian3.normalize(normal, normal);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(1.0, -1.0, 1.0);
Cartesian3.normalize(normal, normal);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(-1.0, -1.0, 1.0);
Cartesian3.normalize(normal, normal);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(-1.0, 1.0, 1.0);
Cartesian3.normalize(normal, normal);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(1.0, 1.0, -1.0);
Cartesian3.normalize(normal, normal);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(1.0, -1.0, -1.0);
Cartesian3.normalize(normal, normal);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(-1.0, 1.0, -1.0);
Cartesian3.normalize(normal, normal);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);

normal = new Cartesian3(-1.0, -1.0, -1.0);
Cartesian3.normalize(normal, normal);
AttributeCompression.octEncode(normal, encoded, rangeMax);
expect(AttributeCompression.octDecode(encoded.x, encoded.y, result, rangeMax)).toEqualEpsilon(normal, epsilon);
});

it('octFloat encoding', function() {
var epsilon = CesiumMath.EPSILON1;

Expand Down