[gnuastro-commits] master c395f2b: Explanation on NaN (blank) values in Arithmetic

[Mohammad Akhlaghi]

branch: master
commit c395f2beee0e54ff7b9660e2b78a9179bb0a27d4
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>

    Explanation on NaN (blank) values in Arithmetic
    
    The fact that NaN values are not equal to anything (even themselves) is
    important and since Arithmetic deals with blank pixels as NaN values, it
    was important to explain this in the book.
    
    Also, an interesting outcome of this property of NaN values is given: how
    you can make a fully zero-valued image based on another.
---
 doc/gnuastro.texi |   25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 9dd411e..89b7703 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -7017,6 +7017,31 @@ produce unpredictable outputs. In any case, the input 
images are not
 affected, they are only read.
 @end cartouche
 
address@hidden
address@hidden
address@hidden pixels:} Currently all Arithmetic operations are internally
+done in double precision floating points. So all blank pixels in the image
+(see @ref{Blank pixels}) will be stored as IEEE NaN values. One particular
+aspect of NaN values is that by definition they will fail on @emph{any}
+comparison, so a NaN is not equal to NaN! Currently, Gnuastro has no way to
+select only blank pixels but we have defined task 14146 to do it when we
+get the chance or someone offers to help.
+
+One way you can exploit this property of the NaN value to your advantage is
+when you want a fully zero-valued image (even over the blank pixels) based
+on an already existing image (with same size and world coordinate system
+settings). The following command will produce this for you:
+
address@hidden
+$ astarithmetic input.fits nan eq --output=all-zeros.fits
address@hidden example
+
address@hidden
+Note that on the command-line you can write NaN in any case (for example
address@hidden, or @command{NAN} are also acceptable). Reading NaN as a
+floating point number in Gnuastro isn't case-sensitive.
address@hidden cartouche
+
 
 @node Invoking astarithmetic,  , Arithmetic operators, Arithmetic
 @subsection Invoking Arithmetic