[gnuastro-commits] master ad12296: ImageCrop's section syntax is inclusive in both bounds

[Mohammad Akhlaghi]

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

    ImageCrop's section syntax is inclusive in both bounds
    
    Until now, ImageCrop's section syntax (for the `--section' option) was
    inclusive for the first point, but not inclusive for the last point. This
    was counter-intuitive and confusing for the user. So with this commit, the
    last point is also inclusive. This was suggested in task #14313 by Lee
    Kelvin.
    
    Also, until now, users (not necessarily Gnuastro developers) could not post
    bugs/tasks or comments on the respective tracker. This was very
    inconvenient. Hence, the permissions on Savannah for these trackers were
    changed so anyone who has a Savannah ID (not necessarily a Gnuastro
    developer), can create an issue and/or submit a comment on one. The book
    was also corrected to reflect this change. For anonymous users, the Support
    tracker is still available.
    
    This fixes task #14313.
---
 bin/imgcrop/crop.c |    8 ++---
 doc/gnuastro.texi  |   92 +++++++++++++++++++++++++++++++---------------------
 2 files changed, 59 insertions(+), 41 deletions(-)

diff --git a/bin/imgcrop/crop.c b/bin/imgcrop/crop.c
index ee8bfa5..57c9014 100644
--- a/bin/imgcrop/crop.c
+++ b/bin/imgcrop/crop.c
@@ -127,7 +127,7 @@ sectionparser(char *section, long *naxes, long *fpixel, 
long *lpixel)
       */
 
       /* Make sure if a number was read at all? */
-      if(tailptr==pt)                /* No number was read!             */
+      if(tailptr==pt)           /* No number was read!                 */
         {
           if(add) read=0;       /* We have a * followed by `:' or `,'. */
           else    continue;
@@ -141,7 +141,7 @@ sectionparser(char *section, long *naxes, long *fpixel, 
long *lpixel)
       if(forl=='f')
         fpixel[dim] = add ? naxes[dim]+read : read;
       else
-        lpixel[dim] = add ? naxes[dim]+read-1 : read-1;
+        lpixel[dim] = add ? naxes[dim]+read : read;
       pt=tailptr;
 
       /* For a check:
@@ -768,8 +768,8 @@ onecrop(struct cropparams *crp)
       sprintf(basename, "ICF%zu", ++p->log[crp->outindex].numimg);
       gal_fits_file_name_in_keywords(basename, img->name, &headers);
       sprintf(regionkey, "%sPIX", basename);
-      sprintf(region, "%ld:%ld,%ld:%ld", fpixel_i[0], lpixel_i[0]+1,
-              fpixel_i[1], lpixel_i[1]+1);
+      sprintf(region, "%ld:%ld,%ld:%ld", fpixel_i[0], lpixel_i[0],
+              fpixel_i[1], lpixel_i[1]);
       gal_fits_add_to_key_ll_end(&headers, TSTRING, regionkey, 0, region, 0,
                                  "Range of pixels used for this output.", 0,
                                  NULL);
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 42ee507..4186a72 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -354,8 +354,8 @@ ImageCrop
 
 Invoking ImageCrop
 
-* astimgcrop options::          A list of all the options with explanation.
-* astimgcrop output::           The outputs of ImageCrop.
+* ImageCrop options::          A list of all the options with explanation.
+* ImageCrop output::           The outputs of ImageCrop.
 
 Arithmetic
 
@@ -6549,19 +6549,19 @@ to be empty, ImageCrop can fill them for you based on 
the input image
 sizes.
 
 @cindex Define section to crop
-To define a box, you need the coordinates of two points: the first pixel in
-the box at (@code{X1}, @code{Y1}) and the pixel which is immediately
-outside of the box (@code{X2, @code{Y2}}), four coordinates in total. The
-four coordinates can be specified with one string in this format:
address@hidden:X2,Y1:Y2}. It is given to the @option{--section}
+To define a box, you need the coordinates of two points: the first
+(@code{X1}, @code{Y1}) and the last pixel (@code{X2}, @code{Y2}) pixel
+positions in the image, or four integer numbers in total. The four
+coordinates can be specified with one string in this format:
address@hidden:X2,Y1:Y2}'. This string is given to the @option{--section}
 option. Therefore, the pixels along the first axis that are
address@hidden@command{X1} and <@command{X2} will be included in the cropped
-image. The same goes for the second axis. Note that each different term
-will be read as an integer, not a float (ImageCrop does not crop below the
-pixel resolution, you can use ImageWarp to shift/warp the image by any
-sub-pixel amount, then crop the warped image, see @ref{ImageWarp}). Also,
-following the FITS standard, pixel indexes along each axis start from
-unity(1) not zero(0).
address@hidden@command{X1} and @address@hidden will be included in
+the cropped image. The same goes for the second axis. Note that each
+different term will be read as an integer, not a float. This is a low-level
+option, for a higher-level way to specify region (any polygon, not just a
+box), please see the @option{--polygon} option in @ref{ImageCrop
+options}. Also note that in the FITS standard, pixel indexes along each
+axis start from unity(1) not zero(0).
 
 @cindex Crop section format
 You can omit any of the values and they will be filled automatically.
@@ -6585,13 +6585,14 @@ replace it with the maximum length of the image in that 
dimension. So
 the input image with 3/4 of the image being covered by blank pixels,
 see @ref{Blank pixels}.
 
-If you feel more comfortable with space characters between the values,
-you can use as many space characters as you wish, just be careful to
-put your value in double quotes, for example
address@hidden"5:200, 123:854"}. If you forget, anything after
-the first space will not be seen by @option{--section}, because the
-unquoted space character is one of the characters that separates
-options on the command-line.
+If you feel more comfortable with space characters between the values, you
+can use as many space characters as you wish, just be careful to put your
+value in double quotes, for example @command{--section="5:200,
+123:854"}. If you forget the quotes, anything after the first space will
+not be seen by @option{--section} and you will most probably get an error
+because the rest of your string will be read as a filename (which most
+probably doesn't exist). See @ref{Command-line} for a description of how
+the command-line works.
 
 
 @node Blank pixels, Invoking astimgcrop, Crop section syntax, ImageCrop
@@ -6656,11 +6657,29 @@ $ astimgcrop --xc=568.342 --yc=2091.719 --iwidth=200 
image.fits
 
 @noindent
 ImageCrop has one mandatory argument which is the input image name(s),
-shown above with @file{ASTRdata ...}. You can use shell expansions,
-for example @command{*} for this if you have lots of images in WCS
-mode. If the crop box centers are in a catalog, you also have to
-provide the catalog name as an argument. Alternatively, you have to
-provide the crop box parameters with command-line options.
+shown above with @file{ASTRdata ...}. You can use shell expansions, for
+example @command{*} for this if you have lots of images in WCS mode. If the
+crop box centers are in a catalog, you also have to provide the catalog
+name as an argument. Alternatively, you have to provide the crop box
+parameters with command-line options. As in all Gnuastro programs, when an
+output is not explicitly set with the @option{--output} option, the output
+filename will be set automatically, see @ref{Automatic output}. For the
+full list of general options to all Gnuastro programs (including
+ImageCrop), please see @ref{Common options}.
+
+Floating point numbers can be used to specify the crop region (except the
address@hidden option, see @ref{Crop section syntax}). In such cases,
+the floating point values will be used to find the desired integer pixel
+indices based on the FITS standard. Hence, ImageCrop ultimately doesn't do
+any sub-pixel cropping (in other words, it doesn't change pixel values). If
+you need such crops, you can use @ref{ImageWarp} to first warp the image to
+the a new pixel grid where your initial floating points can be seen as
+integers, then crop from that with ImageCrop. For example, let's say you
+want a crop from pixels 12.982 to 80.982 along the first dimension. You
+should first translate the image by @mymath{-0.482} (note that the edge of
+a pixel is at integer multiples of @mymath{0.5}). So you should run
+ImageWarp with @option{--translate=-0.482,0} and then crop the warped image
+with @option{--section=13:81}.
 
 @cindex Asynchronous thread allocation
 When in catalog mode, ImageCrop will run in parallel unless you set
@@ -6672,11 +6691,11 @@ and classifies his catalog} for a tutorial on 
effectively using this
 feature.
 
 @menu
-* astimgcrop options::          A list of all the options with explanation.
-* astimgcrop output::           The outputs of ImageCrop.
+* ImageCrop options::          A list of all the options with explanation.
+* ImageCrop output::           The outputs of ImageCrop.
 @end menu
 
address@hidden astimgcrop options, astimgcrop output, Invoking astimgcrop, 
Invoking astimgcrop
address@hidden ImageCrop options, ImageCrop output, Invoking astimgcrop, 
Invoking astimgcrop
 @subsubsection ImageCrop options
 
 The options can be classified into the following contexts: Input,
@@ -6916,7 +6935,7 @@ Operate in WCS mode. See explanations for 
@option{--imgmode}.
 
 
 
address@hidden astimgcrop output,  , astimgcrop options, Invoking astimgcrop
address@hidden ImageCrop output,  , ImageCrop options, Invoking astimgcrop
 @subsubsection ImageCrop output
 When a catalog is given, the value of @option{--output} (see
 @ref{Common options}) will be seen as the directory to store the
@@ -17656,13 +17675,12 @@ features/capabilities) that are to be added to 
Gnuastro.
 @noindent
 All the trackers can be browsed by a (possibly anonymous) visitor, but to
 edit and comment on the Bugs and Tasks trackers, you have to be a
-registered Gnuastro developer. When posting an issue to a tracker, it is
-very important to choose the `Category' and `Item Group' options
-accurately. The first contains a list of all Gnuastro's programs along
-with `Installation', `New program' and `Webpage'. The ``Item Group''
-contains the nature of the issue, for example if it is a `Crash' in the
-software (a bug), or a problem in the documentation (also a bug) or a
-feature request or an enhancement.
+registered on Savannah. When posting an issue to a tracker, it is very
+important to choose the `Category' and `Item Group' options accurately. The
+first contains a list of all Gnuastro's programs along with `Installation',
+`New program' and `Webpage'. The ``Item Group'' contains the nature of the
+issue, for example if it is a `Crash' in the software (a bug), or a problem
+in the documentation (also a bug) or a feature request or an enhancement.
 
 The set of horizontal links on the top of the page (Starting with
 `Main' and `Homepage' and finishing with `News') are the easiest way