Recipe 4.12. Converting Angle Measurements

Problem

You want to work with angle values in ActionScript, but you must convert to the proper units.

Solution

Use the Unit and Converter classes.

Discussion

The _rotation property of a movie clip object is measured in degrees. Every other angle measurement in ActionScript, however, uses radians, not degrees. This can be a problem in two ways. First, if you want to set the _rotation property based on the output of one of ActionScript's trigonometric methods, you must convert the value from radians to degrees. Second, humans generally prefer to work in degrees, which we must convert to radians before feeding to any of the trigonometric methods. Fortunately, the conversion between radians and degrees is simple. To convert from radians to degrees, you need only to multiply by 180/Math.PI. Likewise, to convert from degrees to radians you need only to multiply by the inverse: Math.PI/180. However, you may find it more convenient to simply use the custom Unit and Converter classes.

The Unit and Converter classes are two custom classes found in the ascb.unit package that facilitate conversions between various units of measurement, including degrees, radians, and gradians (there are 400 gradians in a complete circle). The first step is to create a Unit instance that describes the type of unit from which you want to convert. The Unit class provides a large group of constants that make it very convenient. The Unit.DEGREE, Unit.RADIAN, and Unit.GRADIAN constants return new Unit objects that represent degrees, radians, and gradians, respectively. Unit objects have a handful of properties, including name, category, label, and labelPlural:

var degree:Unit = Unit.DEGREE;
trace(degree.name);        // Displays: degree
trace(degree.category);    // Displays: angle
trace(degree.label);       // Displays: degree
trace(degree.labelPlural); // Displays: degrees

Once you've gotten a Unit instance that represents the unit from which you want to convert, you can then retrieve a Converter instance that can convert to a specific type of unit. Use the getConverterTo( ) method, and pass it a reference to a Unit object that represents the type of unit to which you want to convert. For example, the following code creates a Converter object that can convert from degrees to radians:

var converter:Converter = Unit.DEGREE.getConverterTo(Unit.RADIAN);

Once you've created a Converter instance, you can run the convert( ) method, specifying a value you want to convert; for example:

trace(converter.convert(90));

The convertWithLabel( ) method converts the value to a string that includes the appropriate label in the event that you want to display the value:

var converterToRadians:Converter = Unit.DEGREE.getConverterTo(Unit.RADIAN);
var converterToDegrees:Converter = Unit.RADIAN.getConverterTo(Unit.DEGREE);
trace(converterToRadians.convertWithLabel(1));
trace(converterToRadians.convertWithLabel(57.2957795130823));
trace(converterToDegrees.convertWithLabel(1));
trace(converterToDegrees.convertWithLabel(0.0174532925199433));

/* 
   Displays:
   0.0174532925199433 radians
   1 radian
   57.2957795130823 degrees
   1 degree
*/

In the event that you find it more convenient to convert in the opposite direction, you can also use the getConverterFrom( ) method to create a Converter instance that converts one unit to another, for example:

var converter:Converter = Unit.DEGREE.getConverterFrom(Unit.GRADIAN);
trace(converter.convert(100));
trace(converter.convert(23));