com.pixelmed.ucum

Class UCUMAnalyzer

java.lang.Object

com.pixelmed.ucum.UCUMAnalyzer

public class UCUMAnalyzer
extends Object

A class of static methods to convert UCUM code strings into a canonical form and to determine a conversion factor when their canonical forms are equivalent apart from a constant multiplier value.

The canonical form used here is defined to be that involving use of the base units only, or those units that cannot be converted to base units (typically those defined as meaning unity, such as Hounsfield Units for CT, etc.), sorted into a canonical order, with exponents fully expanded, prefixes expanded into constans, constants folded, and from which redundant terms in the numerator and denominator have been eliminated.

Note that the class does not attempt to check the appropriateness of a conversion; the user is responsible for establishing that the two units to be converted are both of the same type of quantity. For example, both Herz (units of frequency) and Becquerel (units of radioactivity) are defined with the same canonical form (s-1), though one represents the number of cycles per second and the other the number of counts per second.

Also, a handful of units cannot be converted because the conversion is not based on a linear multiplication. This includes the units of pH, the measures of level, which are logarithmic (e.g. Bel), and most notably, units of temperature. For the purpose of converting temperature differences, three experimental extensions to UCUM 1.4 are provided, [degK_delta], [degC_delta] and [degF_delta], which can be converted by a constant multiplier. These are useful, for example, in meteorology to convert the atmospheric lapse rate (change in temperature per unit of altitude) from one unit to another, without concern for the absolute temperature.

A main() method is provided for testing and the convenience of command line execution.

For example, the following command extracts the conversion factor from centimetres per second to US furlongs per hour:

        % java -cp ./pixelmed_ucum.jar:./antlr-2.7.5.jar com.pixelmed.ucum.UCUMAnalyzer "cm/s" "[fur_us]/h"
        Conversion factor = 5.588011176022351
 

To illustrate the canonical forms used in the above examples, the following commands generate LISP-like output describing the constant, the numerator and the denominator:

        % java -cp ./pixelmed_ucum.jar:./antlr-2.7.5.jar com.pixelmed.ucum.UCUMAnalyzer "cm/s"
        Canonical form = ( / ( . 0.01  m ) ( .  s ) )
 

        % java -cp ./pixelmed_ucum.jar:./antlr-2.7.5.jar com.pixelmed.ucum.UCUMAnalyzer "[fur_us]/h"
        Canonical form = ( / ( . 0.05588011176022351  m ) ( .  s ) )
 

Constructor Summary

Constructors

Constructor and Description
UCUMAnalyzer()

Method Summary

Modifier and Type	Method and Description
static UCUMCanonicalStructure	getCanonicalForm(String s, int debugMode) Get the canonical form of a UCUM code.
static double	getConversionFactor(String s1, String s2, int debugMode) Attempt to convert one UCUM code into another if their canonical forms are equivalent other than a constant multiplier.
static double	getConversionFactor(UCUMCanonicalStructure c1, UCUMCanonicalStructure c2) Attempt to convert one UCUM code into another if their canonical forms are equivalent other than a constant multiplier.
static void	main(String[] arg) Read UCUM strings from command line arguments or standard input and print their canonical form or attempt to convert between them.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UCUMAnalyzer

public UCUMAnalyzer()

Method Detail

getCanonicalForm

public static UCUMCanonicalStructure getCanonicalForm(String s,
                                                      int debugMode)
                                               throws UCUMConversionException

Get the canonical form of a UCUM code.

Parameters:

s - the UCUM code

debugMode - values greater than zero activate debugging messages

Returns:

the canonical form of a UCUM code

Throws:

UCUMConversionException - if the UCUM code cannot be parsed or a canonical form cannot be generated

getConversionFactor

public static double getConversionFactor(UCUMCanonicalStructure c1,
                                         UCUMCanonicalStructure c2)
                                  throws UCUMConversionException

Attempt to convert one UCUM code into another if their canonical forms are equivalent other than a constant multiplier.

Parameters:

c1 - the canonical form of a UCUM code

c2 - the canonical form of a UCUM code

Returns:

the conversion factor by which to multiply values in c1 units to obtain values in c2 units

Throws:

UCUMConversionException - if the UCUM codes cannot be parsed or their canonical forms are not equivalent

getConversionFactor

public static double getConversionFactor(String s1,
                                         String s2,
                                         int debugMode)
                                  throws UCUMConversionException

Attempt to convert one UCUM code into another if their canonical forms are equivalent other than a constant multiplier.

Parameters:

s1 - a UCUM code

s2 - a UCUM code

debugMode - values greater than zero activate debugging messages

Returns:

the conversion factor by which to multiply values in s1 units to obtain values in s2 units

Throws:

UCUMConversionException - if the UCUM codes cannot be parsed or their canonical forms are not equivalent

main

public static void main(String[] arg)
                 throws Exception

Read UCUM strings from command line arguments or standard input and print their canonical form or attempt to convert between them.

If the first argument is "-v" or "-vv", activate debugging messages.

If there are no (remaining) arguments, read a single UCUM string from the standard input and print its canonical form.

If there is a single (remaining) argument, regard it as a single UCUM string and print its canonical form.

If there are two (remaining) arguments, regard them as UCUM strings and compare their canonical forms for equivalence and print a conversion factor.

Parameters:

arg - array of zero, one, two or three strings

Throws:

Exception