.. include:: references.rst
`UnitConverter`
```````````````
.. autoclass:: pywcs.UnitConverter
:members:
:inherited-members:
:undoc-members:
.. _fits-unit:
FITS unit specification
```````````````````````
Supported units
---------------
The following units are supported by the FITS standard:
**SI base & supplementary units**
====================== ============ =================
Quantity Unit String Meaning
====================== ============ =================
length m metre
mass kg kilogram
time s second of time
plane angle rad radian
solid angle sr steradian
temperature K kelvin
electric current A ampere
amount of substance mol mole
luminous intensity cd candela
====================== ============ =================
**IAU-recognized derived units**
====================== ============ ================= ==================
Quantity Unit String Meaning Equivalence
====================== ============ ================= ==================
frequency Hz hertz s\ :sup:`-1`
energy J joule N m
power W watt J s\ :sup:`-1`
electric potential V volts J C\ :sup:`-1`
force N newton kg m s\ :sup:`-2`
pressure, stress Pa pascal N m\ :sup:`-2`
electric charge C coulomb A s
electric resistance ohm ohm (Ω) V A\ :sup:`-1`
electric conductance S siemens A V\ :sup:`-1`
electric capacitance F farad C V\ :sup:`-1`
magnetic flux Wb weber V s
magnetic flux density T tesla Wb m\ :sup:`-2`
inductance H henry Wb A\ :sup:`-1`
luminous flux lm lumen cd sr
illuminance lx lux lm m\ :sup:`-2`
====================== ============ ================= ==================
**Additional units**
====================== ============ ======================== ============================================
Quantity Unit String Meaning Equivalence
====================== ============ ======================== ============================================
mass u unified atomic mass unit 1.6605387 x 10\ :sup:`-27` kg
mass solMass solar mass 1.9891 x 10\ :sup:`30` kg
plane angle deg degree of arc 1.745533 x 10\ :sup:`-2` rad
plane angle arcsec second of arc 4.848137 x 10\ :sup:`-6` rad
plane angle arcmin minute of arc 2.90888 x 10\ :sup:`-4` rad
time min minute
time h hour
time d day 8.64 x 10\ :sup:`4` s
time yr year (Julian) 3.15576 x10\ :sup:`-7` s (365.25 d)
energy eV electron volt 1.602177 x 10\ :sup:`-19` J
energy erg erg 10\ :sup:`-7` J
energy Ry Rydberg 13.605692 eV
length angstrom angstrom 10\ :sup:`-10` m
length AU astronomical unit 1.49598 x 10\ :sup:`11` m
length lyr light year 9.460530 x 10\ :sup:`-15` m
length pc parsec 3.0857 x 10\ :sup:`-16` m
length solRad solar radius 6.9599 x 10\ :sup:`8` m
events count counts
events photon photons
flux density Jy jansky 10\ :sup:`-16` W m\ :sup:`-2` Hz\ :sup:`-1`
flux density mag (stellar) magnitude
flux density Crab 'crab'
flux density beam beam Jy/beam
flux density solLum solar luminosity
magnetic field G gauss 10\ :sup:`-4` T
area pixel (image/detector) pixel
area voxel 3-d analog of pixel
area barn barn 10\ :sup:`-28` m\ :sup:`2`
device chan (detector) channel
device byte (computer) byte
device bit (computer) bits
device adu A/D converter units
misc bin numerous applications
misc Sun wrt. sun
====================== ============ ======================== ============================================
Potentially unsafe translations of ``"D"``, ``"H"``, and ``"S"``, are
optional, using the *translate_units* parameter.
.. _unit-aliases:
Unit aliases
------------
When converting non-standard units to standard ones, a case-sensitive
match is required for the aliases listed below, in particular the only
recognized aliases with metric prefixes are ``"KM"``, ``"KHZ"``,
``"MHZ"``, and ``"GHZ"``.
========== =============================================================
Unit Recognized aliases
========== =============================================================
Angstrom angstrom
arcmin arcmins, ARCMIN, ARCMINS
arcsec arcsecs, ARCSEC, ARCSECS
beam BEAM
byte Byte
count ct
d day, days, (D), DAY, DAYS
deg degree, degrees, DEG, DEGREE, DEGREES
GHz GHZ
h hr, (H), HR
Hz hz, HZ
kHz KHZ
Jy JY
K kelvin, kelvins, Kelvin, Kelvins, KELVIN, KELVINS
km KM
m metre, meter, metres, meters, M, METRE, METER, METRES, METERS
min MIN
MHz MHZ
Ohm ohm
Pa pascal, pascals, Pascal, Pascals, PASCAL, PASCALS
photon ph
pixel pixels, PIXEL, PIXELS, pix
rad radian, radians, RAD, RADIAN, RADIANS
s sec, second, seconds, (S), SEC, SECOND, SECONDS
V volt, volts, Volt, Volts, VOLT, VOLTS
yr year, years, YR, YEAR, YEARS
========== =============================================================
The aliases ``"angstrom"``, ``"ohm"``, and ``"Byte"`` for (Angstrom,
Ohm, and byte) are recognized by pywcs/wcslib itself as an unofficial
extension of the standard, but they are converted to the standard form
here.
Prefixes
--------
The following metric prefixes are supported:
======= ======= ===================
Prefix String Magnitude
======= ======= ===================
yocto y 10\ :sup:`-24`
zepto z 10\ :sup:`-21`
atto a 10\ :sup:`-18`
femto f 10\ :sup:`-15`
pico p 10\ :sup:`-12`
nano n 10\ :sup:`-9`
micro u 10\ :sup:`-6`
milli m 10\ :sup:`-3`
centi c 10\ :sup:`-2`
deci d 10\ :sup:`-1`
deka da 10\ :sup:`1`
hecto h 10\ :sup:`2`
kilo k 10\ :sup:`3`
Mega M 10\ :sup:`6`
Giga G 10\ :sup:`9`
Tera T 10\ :sup:`12`
Peta P 10\ :sup:`15`
Exa E 10\ :sup:`18`
Zetta Z 10\ :sup:`21`
Yotta Y 10\ :sup:`24`
======= ======= ===================
Table 6 of WCS Paper I lists eleven units for which metric prefixes
are allowed. However, in this implementation only prefixes greater
than unity are allowed for ``"a"`` (annum), ``"yr"`` (year), ``"pc"``
(parsec), ``"bit"``, and ``"byte"``, and only prefixes less than unity
are allowed for ``"mag"`` (stellar magnitude).
Metric prefix ``"P"`` (peta) is specifically forbidden for ``"a"``
(annum) to avoid confusion with ``"Pa"`` (Pascal, not peta-annum).
Note that metric prefixes are specifically disallowed for ``"h"``
(hour) and ``"d"`` (day) so that ``"ph"`` (photons) cannot be
interpreted as pico-hours, nor ``"cd"`` (candela) as centi-days.
Operators
---------
A compound unit is considered to be formed by a series of sub-strings
of component units & mathematical operations. Each of these
sub-strings must be separated by at least one space or a mathematical
operator (``*`` or ``/``).
Multiplication
==============
Multiplicative units can be specified either:
- by simply using one or more preceding spaces, e.g. ``str1 str2``
(The recommended method).
- by the use of a single asterisk (``*``) with optional whitespace,
e.g. ``str1 * str2``.
Division
========
Units which form the denominator of a compound expression can be
specified either:
- by using a slash (``/``) with optional whitespace, e.g. ``str1 /
str2``. If such a syntax is used, it is recommended that no space
is included between the slash and the unit string.
- by raising a multiplicative unit to a negative power (see below).
It should be stressed that the slash character only effects the
sub-string it immediately precedes. Thus, unless brackets are used,
subsequent sub-strings which also form part of the denominator of the
compound expression must also be preceded by a slash. For example,
``str1 /str2 str3`` is equivalent to ``str1 str3 /str2`` whilst ``str1
/str2 /str3`` is equivalent to ``str1 /(str2 * str3)``.
Raising to Powers
=================
A unit string raised to the power *y* is specified:
- by using two asterisks (``**``) followed by the index enclosed
within round brackets and with no preceding or intervening spaces,
e.g. ``str1**(y)`` or ``str1**(-y)``.
However, if *y* is positive, then the brackets need not be included,
but a following space is recommended if additional sub-strings follow.
Use of brackets
===============
Any number of pairs of round brackets (``()``) may be used within the
string for a compound unit in order to prevent ambiguities. As
described within this section, a number of rules always/often require
their use. However, it is suggested that conservative use is made of
such pairs of brackets in order to minimize the total length of
compound strings. (It should be remembered that a maximum of 68
characters are allowed in the card image of keywords.)
Avoidance of underflows & overflows
===================================
The inclusion of numerical factors within the unit string should
generally be avoided (by the use of multiples and/or submultiples of
component basic units).
However, occasionally it may be preferable to include such factors on
the grounds of user-friendliness and/or to minimize the risk of
computer under- or overflows. In such cases, the numerical factor can
simply be considered a basic unit string.
The following additional guidelines are suggested:
- the numerical factor should precede any unit strings
- only powers of 10 are used as numerical factors
Mathematical Operations & Functions
===================================
A number of mathematical operations are supported. It should be noted
that the (round) brackets are mandatory in all cases in which they are
included in the table.
=============== ==================================================
String Meaning
=============== ==================================================
``str1*str2`` Multiplication
``str1 /str2`` Division
``str1**(y)`` Raised to the power *y*
``log(str1)`` Common Logarithm (to base 10)
``ln(str1)`` Natural Logarithm
``exp(str1)`` Exponential (exp\ :sup:`str1`\ )
``sqrt(str1)`` Square root
``sin(str1)`` Sine
``cos(str1)`` Cosine
``tan(str1)`` Tangent
``asin(str1)`` Arc Sine
``acos(str1)`` Arc Cosine
``atan(str1)`` Arc Tangent
``sinh(str1)`` Hyperbolic Sine
``cosh(str1)`` Hyperbolic Cosine
``tanh(str1)`` Hyperbolic Tangent
=============== ==================================================
Function types ``log()``, ``ln()`` and ``exp()`` may only occur at the
start of the units specification.