[gnuastro-commits] master 48466e1: Book: better description --width giving odd-sided crop

[Mohammad Akhlaghi]

branch: master
commit 48466e177ba57f78340bdd4246dc5555423df13a
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Book: better description --width giving odd-sided crop
    
    Until now, the book briefly discussed this feature of the '--width' option
    (in combination with '--center') and even proposed a solution (on how to
    make it even-sided if necessary). But that description wasn't enough and
    could still lead to confusions.
    
    With this commit, to better clarify the situation, a paragraph has been
    added with a more precise description of the reason behind this behavior.
    
    This was suggested by Alejandro Serrano Borlaff.
---
 doc/announce-acknowledge.txt |  1 +
 doc/gnuastro.texi            | 12 ++++++++----
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/doc/announce-acknowledge.txt b/doc/announce-acknowledge.txt
index ea7fa1b..2e37ab1 100644
--- a/doc/announce-acknowledge.txt
+++ b/doc/announce-acknowledge.txt
@@ -1,5 +1,6 @@
 Alphabetically ordered list to acknowledge in the next release.
 
+Alejandro Serrano Borlaff
 Fernando Buitrago
 Mark Calabretta
 Zohreh Ghaffari
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 85fe3c7..000891a 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -12331,16 +12331,20 @@ The units of the coordinates are read based on the 
value to the @option{--mode}
 
 @item -w FLT[,FLT[,...]]
 @itemx --width=FLT[,FLT[,...]]
-Width of the cropped region about its center.
-@option{--width} may take either a single value (to be used for all 
dimensions) or multiple values (a specific value for each dimension).
+Width of the cropped region about coordinate given to @option{--center}.
 If in WCS mode, value(s) given to this option will be read in the same units 
as the dataset's WCS information along this dimension.
-The final output will have an odd number of pixels to allow easy 
identification of the pixel which keeps your requested coordinate (from 
@option{--center} or @option{--catalog}).
+This option may take either a single value (to be used for all dimensions: 
@option{--width=10} in image-mode will crop a @mymath{10\times10} pixel image) 
or multiple values (a specific value for each dimension: @option{--width=10,20} 
in image-mode will crop a @mymath{10\times20} pixel image).
 
 The @code{--width} option also accepts fractions.
-For example if you want the width of your crop to be 3 by 5 arcseconds along 
RA and Dec respectively, you can call it with: @option{--width=3/3600,5/3600}.
+For example if you want the width of your crop to be 3 by 5 arcseconds along 
RA and Dec respectively and you are in wcs-mode, you can use: 
@option{--width=3/3600,5/3600}.
 
+The final output will have an odd number of pixels to allow easy 
identification of the pixel which keeps your requested coordinate (from 
@option{--center} or @option{--catalog}).
 If you want an even sided crop, you can run Crop afterwards with 
@option{--section=":*-1,:*-1"} or @option{--section=2:,2:} (depending on which 
side you don't need), see @ref{Crop section syntax}.
 
+The basic reason for making an odd-sided crop is that your given central 
coordinate will ultimately fall within a discrete pixel in the image (defined 
by the FITS standard).
+When the crop has an odd number of pixels in each dimension, that pixel can be 
very well defined as the ``central'' pixel of the crop, making it unambiguously 
easy to identify.
+However, for an even-sided crop, it will be very hard to identify the central 
pixel (it can be on any of the four pixels adjacent to the central point of the 
image!).
+
 @item -l STR
 @itemx -l FLT:FLT,...
 @itemx --polygon=STR