flux_unit_conversion

jdaviz.core.unit_conversion_utils.flux_unit_conversion(values, original_unit, target_unit, equivalencies=None, with_unit=True)

Converts values from original_unit to target_unit using the provided equivalencies while handling special cases where direct unit conversion is not possible. This function is designed to account for scenarios like conversions involving flux to surface brightness that also require a u.spectral_density equivalency, conversions between per-square pixel surface brightnesses that don’t convert directly, and other flux to surface brightness conversions.

This function should be used for unit conversions when possible instead of directly using Astropy’s unit.to(), as it handles additional logic for special cases.

Parameters:

valuesarray-like or float

The numerical values to be converted.

original_unitUnit or str

The unit of the input values.

target_unitUnit or str

The desired unit to convert to.

equivalencieslist of equivalencies, optional

Unit equivalencies to apply during the conversion.

with_unitbool, optional

If True, the returned value retains its unit. If False, only the numerical values are returned.

Returns:

converted_valuesQuantity or float

The converted values, with or without units based on with_unit. Note that the returned unit may not always match target_unit: if original_unit is a per-steradian surface brightness but target_unit is per-square-pixel (e.g. the app display unit is stuck in pix2 because the first loaded dataset had no solid angle component), the steradian is preserved rather than converted to pixels. Callers that need the unit actually applied (rather than assuming it matches target_unit) should call with with_unit=True and use the returned Quantity’s .unit.

Raises:

astropy.units.UnitConversionError

If the conversion between original_unit and target_unit fails despite the provided equivalencies.