[gnuastro-commits] master 9c30017 2/2: Book: added example usage of box-around-ellipse Arithmetic operator

[Mohammad Akhlaghi]

branch: master
commit 9c300178bb4d0a4ee58e8c525dde8759750ddbe3
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Book: added example usage of box-around-ellipse Arithmetic operator
    
    The newly added 'box-around-ellipse' operator will return two operands on
    the stack (unlike most other operators that only return a single
    operand). In some situations, users may want to treat each separately, but
    if they aren't experienced enough, it may be confusing/impossible to do so.
    
    With this commit, an example has been added to show how it is possible to
    treat each output separately with the 'set-' operator.
---
 doc/gnuastro.texi | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index a49737a..43a5b05 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -13104,6 +13104,20 @@ $ astarithmetic a.fits b.fits pa.fits 
box-around-ellipse \
                 tofilefree-h.fits -ow.fits -g1
 @end example
 
+Finally, if you need to treat the width and height separately for further 
processing, you can call the @code{set-} operator two times afterwards like 
below.
+Recall that the @code{set-} operator will pop the top operand, and put it in 
memory with a certain name, bringing the next operand to the top of the stack.
+
+For example let's assume @file{catalog.fits} has atleast three columns 
@code{MAJOR}, @code{MINOR} and @code{PA} which specify the major axis, minor 
axis and position angle respectively.
+But you want the final width and height in 32-bit floating point numbers (not 
the default 64-bit, which may be too much precision in many scenarios).
+You can do this with the command below (note you can also break lines with 
@key{\}, within the single-quote environment)
+
+@example
+$ asttable catalog.fits \
+           -c'arith MAJOR MINOR PA box-around-ellipse \
+                    set-height set-width \
+                    width float32 height float32'
+@end example
+
 @item makenew
 Create a new dataset that only has zero values.
 The number of dimensions is read as the first popped operand and the number of 
elements along each dimension are the next popped operand (in reverse of the 
popping order).