diff --git a/doc/source/user_guide/data_types.txt b/doc/source/user_guide/data_types.txt index 1db55543..9801c244 100644 --- a/doc/source/user_guide/data_types.txt +++ b/doc/source/user_guide/data_types.txt @@ -14,13 +14,13 @@ Data type Range uint8 0 to 255 uint16 0 to 65535 uint32 0 to 2\ :sup:`32` -float 0 to 1 +float -1 to 1 int8 -128 to 127 int16 -32768 to 32767 int32 -2\ :sup:`31` to 2\ :sup:`31` - 1 ========= ================================= -Note that float images are restricted to the range 0 to 1 even though the data +Note that float images are restricted to the range -1 to 1 even though the data type itself can exceed this range; all integer dtypes, on the other hand, have pixel intensities that can span the entire data type range. Currently, *64-bit (u)int images are not supported*. @@ -142,6 +142,24 @@ By default, ``rescale_intensity`` stretches the values of ``in_range`` to match the range of the dtype. +Note about negative values +========================== + +People very often represent images in signed dtypes, even though they only +manipulate the positive values of the image (e.g., using only 0-127 in an int8 +image). For this reason, conversion functions *only spread the positive values* +of a signed dtype over the entire range of an unsigned dtype. In other words, +negative values are clipped to 0 when converting from signed to unsigned +dtypes. (Negative values are preserved when converting between signed dtypes.) +To prevent this clipping behavior, you should rescale your image beforehand:: + + >>> image = exposure.rescale_intensity(img_int32, out_range=(0, 2**31 - 1)) + >>> img_uint8 = img_as_ubyte(image) + +This behavior is symmetric: The values in an unsigned dtype are spread over +just the positive range of a signed dtype. + + References ==========