From c3b5cd1023320f21220cca2339c5f5618b97116b Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Mon, 10 Sep 2012 00:25:52 -0400 Subject: [PATCH 1/2] DOC: Add note about negative dtypes --- doc/source/user_guide/data_types.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/source/user_guide/data_types.txt b/doc/source/user_guide/data_types.txt index 1db55543..76d04862 100644 --- a/doc/source/user_guide/data_types.txt +++ b/doc/source/user_guide/data_types.txt @@ -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 ========== From 2c55732fba6dc885ec02eacd9aa8d484fd69462a Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Mon, 10 Sep 2012 00:27:30 -0400 Subject: [PATCH 2/2] DOC: float dtype changed from (0, 1) to (-1, 1). The dtype range was changed long ago, but this doc had not been updated to match this behavior. --- doc/source/user_guide/data_types.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/user_guide/data_types.txt b/doc/source/user_guide/data_types.txt index 76d04862..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*.