[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnuastro-commits] master e03e9ea: Corrections in library and manual
|
From: |
Mohammad Akhlaghi |
|
Subject: |
[gnuastro-commits] master e03e9ea: Corrections in library and manual |
|
Date: |
Thu, 20 Jul 2017 10:59:52 -0400 (EDT) |
branch: master
commit e03e9ea4f380a9033326f5bc51d89970fb03dfa6
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>
Corrections in library and manual
Some small issues were found in the library that are corrected with this
commit and are listed below. Also, the "Invoking MakeProfiles" section of
the manual was out-dated, so it was checked and edited to reflect the more
recent behaviors of this program better.
The changes in the libraries (from the NEWS file):
`gal_data_free_contents': when the input `gal_data_t' is a tile, its
`array' element will not be freed. This enables safe usage of this
function (and thus `gal_data_free') on tiles without worrying about the
memory block associated with the tile.
`gal_box_bound_ellipse' is the new name for the old
`gal_box_ellipse_in_box' (to be more clear and avoid repetition of the
term `box'). The input position angle is now also in degrees, not
radians.
`GAL_TILE_PARSE_OPERATE' (only when `OTHER' is given) can now parse and
operate on different datasets independent of the size of allocated block
of memory (the tile sizes of `IN' and `OTHER' have to be idential, but
not their allocated blocks of memory). Until now, it was necessary for
the two blocks to have the same size and this is no longer the case.
---
NEWS | 20 +-
bin/mkprof/mkprof.c | 4 +-
bin/mkprof/ui.c | 4 +-
doc/gnuastro.texi | 854 ++++++++++++++++++++++++++++------------------------
lib/box.c | 40 +--
lib/data.c | 2 +-
lib/gnuastro/box.h | 4 +-
lib/gnuastro/tile.h | 127 +++++---
lib/tile.c | 18 +-
9 files changed, 602 insertions(+), 471 deletions(-)
diff --git a/NEWS b/NEWS
index cc5d6c6..dac6478 100644
--- a/NEWS
+++ b/NEWS
@@ -58,8 +58,15 @@ GNU Astronomy Utilities NEWS -*-
outline -*-
`--crpix1', `--crpix2', `--crval1', `--crval2' and `--resolution'
options.
- `gal_fits_img_info' now also returns the name and units of the dataset
- (if they aren't NULL). So it takes two extra arguments.
+ `gal_data_free_contents': when the input `gal_data_t' is a tile, its
+ `array' element will not be freed. This enables safe usage of this
+ function (and thus `gal_data_free') on tiles without worrying about the
+ memory block associated with the tile.
+
+ `gal_box_bound_ellipse' is the new name for the old
+ `gal_box_ellipse_in_box' (to be more clear and avoid repetition of the
+ term `box'). The input position angle is now also in degrees, not
+ radians.
`gal_box_overlap' now works on data of any dimensionality and thus also
needs the number of dimensions (elements in each input array).
@@ -68,10 +75,19 @@ GNU Astronomy Utilities NEWS -*-
outline -*-
argument and the number of dimensions as another. This allows it to work
on any dimensionality.
+ `gal_fits_img_info' now also returns the name and units of the dataset
+ (if they aren't NULL). So it takes two extra arguments.
+
`gal_wcs_pixel_scale' now replaces the old `gal_wcs_pixel_scale_deg',
since it doesn't only apply to degrees. The pixel scale units are defined
by the units of the WCS.
+ `GAL_TILE_PARSE_OPERATE' (only when `OTHER' is given) can now parse and
+ operate on different datasets independent of the size of allocated block
+ of memory (the tile sizes of `IN' and `OTHER' have to be idential, but
+ not their allocated blocks of memory). Until now, it was necessary for
+ the two blocks to have the same size and this is no longer the case.
+
** Bug fixes
MakeProfiles long options on 32bit big endian systems (bug #51341).
diff --git a/bin/mkprof/mkprof.c b/bin/mkprof/mkprof.c
index 131519a..5a46b58 100644
--- a/bin/mkprof/mkprof.c
+++ b/bin/mkprof/mkprof.c
@@ -264,8 +264,8 @@ mkprof_build(void *inparam)
if( p->f[id] == PROFILE_POINT )
mkp->width[0]=mkp->width[1]=1;
else
- gal_box_ellipse_in_box(mkp->truncr, mkp->q*mkp->truncr,
- p->p[id]*DEGREESTORADIANS, mkp->width);
+ gal_box_bound_ellipse(mkp->truncr, mkp->q*mkp->truncr, p->p[id],
+ mkp->width);
diff --git a/bin/mkprof/ui.c b/bin/mkprof/ui.c
index f1c3b66..ea82f54 100644
--- a/bin/mkprof/ui.c
+++ b/bin/mkprof/ui.c
@@ -1109,8 +1109,8 @@ ui_prepare_canvas(struct mkprofparams *p)
half of it for the shift. */
setshift=1;
truncr = p->tunitinp ? p->t[i] : p->t[i] * p->r[i]/2;
- gal_box_ellipse_in_box(truncr, p->q[i]*truncr,
- p->p[i]*DEGREESTORADIANS, width);
+ gal_box_bound_ellipse(truncr, p->q[i]*truncr, p->p[i],
+ width);
}
/* Either set the shifts to zero or to the values set from
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 6684ed7..62ede17 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -488,8 +488,9 @@ Modeling basics
Invoking MakeProfiles
* MakeProfiles catalog:: Required catalog properties.
-* MakeProfiles options:: Full list of MakeProfiles options.
-* MakeProfiles output:: The generated outputs.
+* MakeProfiles profile settings:: Configuration parameters for all profiles.
+* MakeProfiles output dataset:: The canvas/dataset to build profiles over.
+* MakeProfiles log file:: A description of the optional log file.
MakeNoise
@@ -1540,18 +1541,19 @@ suggestions during the GNU evaluation process. Bob
Proulx from Savannah,
has kindly supported Gnuastro's project webpage on Savannah and the
management of its version controlled source server there.
address@hidden To the developers: if you would like to thank someone, please
change the
address@hidden `and' before the last name to a comma (','), then add " and
Firstname
address@hidden Familyname'' after the last name.
-We would also like to gratefully thank Mohammad-reza Khellat, Alan Lefor,
-Yahya Sefidbakht, Francesco Montanari, Ole Streicher, Nicolas Bouché, Rosa
-Calvi, Lee Kelvin, Guillaume Mahler, William Pence, David Valls-Gabaud,
-Christopher Willmer, for their useful and constructive comments and
-suggestions. Finally we should thank all the (sometimes anonymous)
-developers in various online forums which patiently answered all our small
-(but important) technical questions. All work on Gnuastro has been
-voluntary, but we are most grateful to the following institutions (in
-chronological order) for hosting us in our research:
address@hidden To the developers: please keep this in the same order as the
THANKS file
address@hidden (alphabetical, except for the names in the paragraph above).
+We would also like to gratefully thank (in alphabetical order) Roland
+Bacon, Nicolas Bouché, Adrian Bunk, Rosa Calvi, Antonio Diaz Diaz, Raúl
+Infante Sainz, Lee Kelvin, Mohammad-Reza Khellat, Alan Lefor, Guillaume
+Mahler, Francesco Montanari, William Pence, Yahya Sefidbakht, Ole
+Streicher, Ignacio Trujillo, David Valls-Gabaud and Christopher Willmer for
+their useful and constructive comments and suggestions. Finally we should
+thank all the (sometimes anonymous) people in various online forums which
+patiently answered all our small (but important) technical questions. All
+work on Gnuastro has been voluntary, but we are most grateful to the
+following institutions (in chronological order) for hosting us in our
+research:
@quotation
Ministry of education, culture, sports, science and technology (MEXT),
address@hidden
@@ -1931,8 +1933,7 @@ $ astmkprof -P
# Output:
type float32 # Type of output: e.g., int16, float32, etc...
- naxis1 1000 # Number of pixels along first FITS axis.
- naxis2 1000 # Number of pixels along second FITS axis.
+ naxis 1000,1000 # Number of pixels along first FITS axis.
oversample 5 # Scale of oversampling (>0 and odd).
[[[ ... Truncated lines ... ]]]
@@ -8931,7 +8932,7 @@ equivalent to this piece of C:
@example
size_t i;
long a[100];
-float b[100], out;
+float b[100], out[100];
for(i=0;i<100;++i) out[i]=a[i]+b[i];
@end example
@@ -10653,12 +10654,12 @@ transpose of the one discussed here.}.
@cindex Multiplication, matrix
@cindex Non-commutative operations
@cindex Operations, non-commutative
-In @ref{Warping basics} we saw how one basic warping/transformation
-can be represented with a 3 by 3 matrix. To make more complex warpings
-these matrices have to be multiplied through matrix
-multiplication. However matrix multiplication is not commutative, so
-the order of the set of matrices you use for the multiplication is
-going to be very important.
+In @ref{Warping basics} we saw how a basic warp/transformation can be
+represented with a matrix. To make more complex warpings (for example to
+define a translation, rotation and scale as one warp) the individual
+matrices have to be multiplied through matrix multiplication. However
+matrix multiplication is not commutative, so the order of the set of
+matrices you use for the multiplication is going to be very important.
The first warping should be placed as the left-most matrix. The second
warping to the right of that and so on. The second transformation is
@@ -14206,20 +14207,21 @@ distance on the major axis to the center of an
ellipse which is located at
want to find @mymath{r_{el}} of a point located at @mymath{(i,j)} (in the
image coordinate system) from the center of the ellipse with axis ratio
@mymath{q} and position angle @mymath{\theta}. First the coordinate system
-is address@hidden not confuse this with the rotation matrix of
address@hidden basics}. In that equation, the point is rotated, here the
-coordinates are rotated and the point is fixed.} by @mymath{\theta} to get
-the new rotated coordinates of that point @mymath{(i_r,j_r)}:
+is address@hidden not confuse the signs of @mymath{sin} with the
+rotation matrix defined in @ref{Warping basics}. In that equation, the
+point is rotated, here the coordinates are rotated and the point is fixed.}
+by @mymath{\theta} to get the new rotated coordinates of that point
address@hidden(i_r,j_r)}:
address@hidden(i,j)=+(i_c-i)\cos(\theta)+(j_c-j)\sin(\theta)}
address@hidden(i,j)=-(i_c-i)\sin(\theta)+(j_c-j)\cos(\theta)}
address@hidden(i,j)=+(i_c-i)\cos\theta+(j_c-j)\sin\theta}
address@hidden(i,j)=-(i_c-i)\sin\theta+(j_c-j)\cos\theta}
@cindex Elliptical distance
@noindent Recall that an ellipse is defined by @mymath{(i_r/a)^2+(j_r/b)^2=1}
and that we defined @mymath{r_{el}\equiv{a}}. Hence, multiplying all
elements of the the ellipse definition with @mymath{r_{el}^2} we get the
elliptical distance at this point point located:
address@hidden/q^2} }. To place the radial profiles
address@hidden(j_r/q)^2}}. To place the radial profiles
explained below over an ellipse, @mymath{f(r_{el})} is calculated based on
the functional radial profile desired.
@@ -14227,13 +14229,13 @@ the functional radial profile desired.
@cindex Inside-out construction
@cindex Making profiles pixel by pixel
@cindex Pixel by pixel making of profiles
-MakeProfiles builds the profile starting from the nearest pixel in the
-image to the given profile center. The profile value is calculated for that
-central pixel using monte carlo integration, see @ref{Sampling from a
-function}. The next pixel is the next nearest neighbor to the central pixel
-as defined by @mymath{r_{el}}. This process goes on until the profile is
-fully built upto the trunctation radius. This is done fairly efficiently
-using a breadth first parsing
+MakeProfiles builds the profile starting from the nearest element (pixel in
+an image) in the dataset to the profile center. The profile value is
+calculated for that central pixel using monte carlo integration, see
address@hidden from a function}. The next pixel is the next nearest neighbor
+to the central pixel as defined by @mymath{r_{el}}. This process goes on
+until the profile is fully built upto the trunctation radius. This is done
+fairly efficiently using a breadth first parsing
address@hidden@url{http://en.wikipedia.org/wiki/Breadth-first_search}}
which is implemented through an ordered linked list.
@@ -14481,15 +14483,15 @@ Carlo integration and only use the central pixel
value.
@cindex Inside-out construction
The ordering of the pixels in this inside-out construction is based on
@mymath{r=\sqrt{(i_c-i)^2+(j_c-j)^2}}, not @mymath{r_{el}}, see
address@hidden an ellipse}. When the axis ratios are large (near one)
-this is fine. But when they are small and the object is highly
-elliptical, it might seem more reasonable to follow @mymath{r_{el}}
-not @mymath{r}. The problem is that the gradient is stronger in pixels
-with smaller @mymath{r} (and larger @mymath{r_{el}}) than those with
-smaller @mymath{r_{el}}. In other words, the gradient is strongest
-along the minor axis. So if the next pixel is chosen based on
address@hidden, the tolerance level will be reached sooner and lots
-of pixels with large fractional differences will be missed.
address@hidden an ellipse}. When the axis ratios are large (near one) this
+is fine. But when they are small and the object is highly elliptical, it
+might seem more reasonable to follow @mymath{r_{el}} not @mymath{r}. The
+problem is that the gradient is stronger in pixels with smaller @mymath{r}
+(and larger @mymath{r_{el}}) than those with smaller @mymath{r_{el}}. In
+other words, the gradient is strongest along the minor axis. So if the next
+pixel is chosen based on @mymath{r_{el}}, the tolerance level will be
+reached sooner and lots of pixels with large fractional differences will be
+missed.
Monte Carlo integration uses a random number of points. Thus,
every time you run it, by default, you will get a different
@@ -14694,9 +14696,9 @@ array and the output image are kept and added to the
output array.
@node Invoking astmkprof, , Profile magnitude, MakeProfiles
@subsection Invoking MakeProfiles
-MakeProfiles will make any number of profiles specified in a catalog
-either individually or in one image. The executable name is
address@hidden with the following general template
+MakeProfiles will make any number of profiles specified in a catalog either
+individually or in one image. The executable name is @file{astmkprof} with
+the following general template
@example
$ astmkprof [OPTION ...] [Catalog]
@@ -14725,28 +14727,40 @@ $ astmkprof --individual --oversample 3
--naxis=500,500 catalog.txt
@noindent
The parameters of the mock profiles can either be given through a catalog
-(which stores the parameters of many mock profiles), or the
address@hidden option (see @ref{MakeProfiles options}). The catalog can
-be in the FITS ASCII, FITS binary format, or plain text formats (see
address@hidden). The columns related to each parameter can be determined both
-by number, or by match/search criteria using the column names, units, or
-comments. with the options ending in @option{col}, see below.
+(which stores the parameters of many mock profiles, see @ref{MakeProfiles
+catalog}), or the @option{--kernel} option (see @ref{MakeProfiles output
+dataset}). The catalog can be in the FITS ASCII, FITS binary format, or
+plain text formats (see @ref{Tables}). The columns related to each
+parameter can be determined both by number, or by match/search criteria
+using the column names, units, or comments. with the options ending in
address@hidden, see below.
Without any file given to the @option{--background} option, MakeProfiles
will make a zero-valued image and build the profiles on that (its size and
-main WCS parameters can also be defined through the options). Besides the
-main/merged image containing all the profiles in the catalog, it is also
-possible to build individual images for each profile (only enclosing one
-full profile to its truncation radius) with the @option{--individual}
-option.
+main WCS parameters can also be defined through the options described in
address@hidden output dataset}). Besides the main/merged image
+containing all the profiles in the catalog, it is also possible to build
+individual images for each profile (only enclosing one full profile to its
+truncation radius) with the @option{--individual} option.
If an image is given to the @option{--background} option, the pixels of
that image are used as the background value for every pixel. The flux value
of each profile pixel will be added to the pixel in that background
value. In this case, the values to all options relating to the output size
and WCS will be ignored if specified (for example @option{--oversample},
address@hidden, @option{--naxis2} and @option{--prepforconv}) on the
-command-line or in the configuration files.
address@hidden and @option{--prepforconv}) on the command-line or in the
+configuration files.
+
+The sections below discuss the options specific to MakeProfiles based on
+context: the input catalog settings which can have many rows for different
+profiles are discussed in @ref{MakeProfiles catalog}, in @ref{MakeProfiles
+profile settings}, we discuss how you can set general profile settings
+(that are the same for all the profiles in the catalog). Finally
address@hidden output dataset} and @ref{MakeProfiles log file} discuss
+the outputs of MakeProfiles and how you can configure them. Besides these,
+MakeProfiles also supports all the common Gnuastro program options that are
+discussed in @ref{Common options}, so please flip through them is well for
+a more comfortable usage.
Please see @ref{Sufi simulates a detection} for a very complete tutorial
explaining how one could use MakeProfiles in conjunction with other
@@ -14754,35 +14768,40 @@ Gnuastro's programs to make a complete simulated
image of a mock galaxy.
@menu
* MakeProfiles catalog:: Required catalog properties.
-* MakeProfiles options:: Full list of MakeProfiles options.
-* MakeProfiles output:: The generated outputs.
+* MakeProfiles profile settings:: Configuration parameters for all profiles.
+* MakeProfiles output dataset:: The canvas/dataset to build profiles over.
+* MakeProfiles log file:: A description of the optional log file.
@end menu
address@hidden MakeProfiles catalog, MakeProfiles options, Invoking astmkprof,
Invoking astmkprof
address@hidden MakeProfiles catalog, MakeProfiles profile settings, Invoking
astmkprof, Invoking astmkprof
@subsubsection MakeProfiles catalog
-The catalog can be in the FITS ASCII, FITS binary format, or plain text
-formats (see @ref{Tables}). Its columns can be ordered in any desired
-manner, you can specify which columns belong to which parameters using the
-set of options ending with @option{col} in @ref{MakeProfiles options}. For
-example through the @option{--xcol} and @option{--rcol} options, you can
-specify the column that contains the X axis position of the profile center
-and the radial parameter for the profile. See @ref{Selecting table columns}
-for a thorough discussion on how to identify a column in the input catalog.
-
-The value for the profile center in the catalog (in the @option{--xcol} and
address@hidden columns) can be a floating point number so the profile
-center can be on any sub-pixel position. Note that pixel positions in the
-FITS standard start from 1 and an integer is the pixel center. So a 2D
-image actually starts from the position (0.5, 0.5). When a
address@hidden image with WCS information is provided, you may also
-use RA and Dec to identify the center of each profile.
+The catalog containing information about each profile can be in the FITS
+ASCII, FITS binary, or plain text formats (see @ref{Tables}). Its columns
+can be ordered in any desired manner. You can specify which columns belong
+to which parameters using the set of options discussed below. For example
+through the @option{--rcol} and @option{--tcol} options, you can specify
+the column that contains the radial parameter for each profile and its
+truncation respectively. See @ref{Selecting table columns} for a thorough
+discussion on the values to these options.
+
+The value for the profile center in the catalog (the @option{--ccol}
+option) can be a floating point number so the profile center can be on any
+sub-pixel position. Note that pixel positions in the FITS standard start
+from 1 and an integer is the pixel center. So a 2D image actually starts
+from the position (0.5, 0.5), which is the bottom-left corner of the first
+pixel. When a @option{--background} image with WCS information is provided
+or you specify the WCS parameters with the respective options, you may also
+use RA and Dec to identify the center of each profile (see the
address@hidden option below).
In MakeProfiles, profile centers do not have to be in (overlap with) the
final image. Even if only one pixel of the profile within the truncation
radius overlaps with the final image size, the profile is built and
included in the final image image. Profiles that are completely out of the
-image will not be created. You can use the output log file to see which
-profiles were within the image.
+image will not be created (unless you explicity ask for it with the
address@hidden option). You can use the output log file (created
+with @option{--log} to see which profiles were within the image, see
address@hidden options}.
If PSF profiles (Moffat or Gaussian, see @ref{PSF}) are in the catalog and
the profiles are to be built in one image (when @option{--individual} is
@@ -14798,156 +14817,98 @@ unity, you have to set their magnitudes in the
catalog to the zero-point
magnitude and be sure that the central positions of the profiles don't have
any fractional part (the PSF center has to be in the center of the pixel).
-
address@hidden MakeProfiles options, MakeProfiles output, MakeProfiles catalog,
Invoking astmkprof
address@hidden MakeProfiles options
-The common options that are shared by Gnuastro programs, are fully
-explained in @ref{Common options} and are not repeated here. Since
-there are no image inputs, address@hidden option is ignored. The
-options can be classified into the following categories: Output,
-Profiles, Catalog and WCS. Below each one is reviewed.
-
address@hidden
-Output:
-
address@hidden @option
-
address@hidden -E STR/INT,FLT[,FLT,[...]]
address@hidden --kernel=STR/INT,FLT[,FLT,[...]]
-Only build one kernel profile with the parameters given as the values to
-this option. The different values must be separated by a comma
-(@key{,}). The first value identifies the radial function of the profile,
-either through a string or through a number (see description of
address@hidden below). Each radial profile needs a different total number
-of parameters: S@'ersic and Moffat functions need 3 parameters: radial,
-S@'ersic index or Moffat @mymath{\beta}, and truncation radius. The
-Gaussian function needs two parameters: radial and truncation radius. The
-point function doesn't need any parameters and flat and circumference
-profiles just need one parameter (truncation radius).
-
-The PSF or kernel is a unique (and highly constrained) type of profile: the
-sum of its pixels must be one, its center must be the center of the central
-pixel (in an image with an odd number of pixels on each side), and commonly
-it is circular, so its axis ratio and position angle are one and zero
-respectively. Kernels are commonly necessary for various data analysis and
-data manipulation steps (for example see @ref{Convolve}, and
address@hidden Because of this it is inconvenient to define a catalog
-with one row and many zero valued columns (for all the non-necessary
-parameters). Hence, with this option, it is possible to create a kernel
-with MakeProfiles without the need to create a catalog. Here are some
-examples:
+The list of options directly related to the input catalog columns is shown
+below.
@table @option
address@hidden --kernel=moffat,3,2.8,5
-A Moffat kernel with FWHM of 3 pixels, @mymath{\beta=2.8} which is
-truncated at 5 times the FWHM.
-
address@hidden --kernel=gaussian,2,3
-A Gaussian kernel with FWHM of 2 pixels and truncated at 3 times the FWHM.
address@hidden table
-
-
address@hidden -k STR
address@hidden --background=STR
-A background image FITS file to build the profiles on. The extension that
-contains the image should be specified with the @option{--backhdu} option,
-see below. When a background image is specified, it will be used to derive
-all the information about the output image. Hence, the following options
-will be ignored: @option{--naxis1}, @option{--naxis2}, @option{--crpix1},
address@hidden, @option{--crval1}, @option{--crval2},
address@hidden, @option{--oversample}, and data type (see
address@hidden in @ref{Input output options}).
-The image will act like a canvas to build the profiles on: profile pixel
-values will be summed with the background image pixel values. With the
address@hidden option you can disable this behavior and replace the
-profile pixels with the background pixels. If you want to use all the image
-information above, except for the pixel values (you want to have a blank
-canvas to build the profiles on, based on an input image), you can call
address@hidden, to set all the input image's pixels to zero before
-starting to build the profiles over it (this is done in memory after
-reading the input, so nothing will happen to your input file).
-
address@hidden -B STR/INT
address@hidden --backhdu=STR/INT
-The header data unit (HDU) of the file given to @option{--background}.
address@hidden --ccol=STR/INT
+Center coordinate column for each dimension. This option must be called two
+times to define the center coordinates in an image. For example
address@hidden and @option{--ccol=DEC} (along with @option{--mode=wcs})
+will inform MakeProfiles to look into the catalog columns named @option{RA}
+and @option{DEC} for the Right Ascension and Declination of the profile
+centers.
address@hidden -x INT,INT
address@hidden --naxis=INT,INT
-The number of pixels along each dimension axis of the output in FITS
-order. This is before over-sampling. For example if you call MakeProfiles
-with @option{--naxis=100,150 --oversample=5} (assuming no shift due for
-later convolution), then the final image size along the first axis will be
-500 by 750 pixels. Fractions are acceptable as values for each dimension,
-however, they must reduce to an integer, so @option{--naxis=150/3,300/3} is
-acceptable but @option{--naxis=150/4,300/4} is not.
address@hidden --fcol=INT/STR
+The functional form of the profile with one of the values below depending
+on the desired profile. The column can contain either the numeric codes
+(for example address@hidden') or string characters (for example
address@hidden'). The numeric codes are easier to use in scripts which
+generate catalogs with hundreds or thousands of profiles.
-When viewing a FITS image in DS9, the first FITS dimension is in the
-horizontal direction and the second is vertical. As an example, the image
-created with the example above will have 500 pixels horizontally and 750
-pixels vertically.
+The string format can be easier when the catalog is to be written/checked
+by hand/eye before running MakeProfiles. It is much more readable and
+provides a level of documentation. All Gnuastro's recognized table formats
+(see @ref{Recognized table formats}) accept string type columns. To have
+string columns in a plain text table/catalog, see @ref{Gnuastro text table
+format}.
-If a background image is specified, this option is ignored.
address@hidden
address@hidden
+S@'ersic profile with address@hidden' or address@hidden'.
address@hidden
+Moffat profile with address@hidden' or address@hidden'.
address@hidden
+Gaussian profile with address@hidden' or address@hidden'.
address@hidden
+Point source with address@hidden' or address@hidden'.
address@hidden
+Flat profile with address@hidden' or address@hidden'.
address@hidden
+Circumference profile with address@hidden' or address@hidden'. A fixed
+value will be used for all pixels between the truncation radius
+(@mymath{r_t}) and @mymath{r_t-w} (@mymath{w} is the value to the
address@hidden).
address@hidden itemize
address@hidden -s INT
address@hidden --oversample=INT
-The scale to over-sample the profiles and final image. If not an odd
-number, will be added by one, see @ref{Oversampling}. Note that this
address@hidden will remain active even if an input image is
-specified. If your input catalog is based on the background image, be sure
-to set @option{--oversample=1}.
address@hidden --rcol=STR/INT
+The radius parameter of the profiles. Effective radius (@mymath{r_e}) if
+S@'ersic, FWHM if Moffat or Gaussian.
address@hidden --psfinimg
-Build the possibly existing PSF profiles (Moffat or Gaussian) in the
-catalog into the final image. By default they are built separately so
-you can convolve your images with them, thus their magnitude and
-positions are ignored. With this option, they will be built in the
-final image like every other galaxy profile. To have a final PSF in
-your image, make a point profile where you want the PSF and after
-convolution it will be the PSF.
address@hidden --ncol=STR/INT
+The S@'ersic index (@mymath{n}) or Moffat @mymath{\beta}.
address@hidden -i
address@hidden --individual
address@hidden Individual profiles
address@hidden Build individual profiles
-If this option is called, each profile is created in a separate FITS
-file within the same directory as the output and the row number of the
-profile (starting from zero) in the name. The file for each row's
-profile will be in the same directory as the final combined image of
-all the profiles and will have the final image's name as a suffix. So
-for example if the final combined image is named
address@hidden/out/fromcatalog.fits}, then the first profile that will be
-created with this option will be named
address@hidden/out/0_fromcatalog.fits}.
address@hidden --pcol=STR/INT
+The position angle (in degrees) of the profiles relative to the first FITS
+axis (horizontal when viewed in SAO ds9).
-Since each image only has one full profile out to the truncation
-radius the profile is centered and so, only the sub-pixel position of
-the profile center is important for the outputs of this option. The
-output will have an odd number of pixels. If there is no oversampling,
-the central pixel will contain the profile center. If the value to
address@hidden is larger than unity, then the profile center is
-on any of the central @option{--oversample}'d pixels depending on the
-fractional value of the profile center.
address@hidden --qcol=STR/INT
+The axis ratio of the profiles (minor axis divided by the major axis in a
+2D ellipse).
-If the fractional value is larger than half, it is on the bottom half
-of the central region. This is due to the FITS definition of a real
-number position: The center of a pixel has fractional value
address@hidden so each pixel contains these fractions: .5 -- .75 -- .00
-(pixel center) -- .25 -- .5.
address@hidden --mcol=STR/INT
+The total pixelated magnitude of the profile within the truncation radius,
+see @ref{Profile magnitude}.
address@hidden -m
address@hidden --nomerged
-Don't make a merged image. By default after making the profiles, they
-are added to a final image with sides of @option{--naxis1} and
address@hidden if they overlap with it.
address@hidden --tcol=STR/INT
+The truncation radius of this profile. By default it is in units of the
+radial parameter of the profile (the value in the @option{--rcol} of the
+catalog). If @option{--tunitinp} is given, this value is interpreted in
+units of pixels (prior to oversampling) irrespective of the profile.
@end table
address@hidden
-Profiles:
address@hidden MakeProfiles profile settings, MakeProfiles output dataset,
MakeProfiles catalog, Invoking astmkprof
address@hidden MakeProfiles profile settings
+
+The profile parameters that differ between each created profile are
+specified through the columns in the input catalog and described in
address@hidden catalog}. Besides those there are general settings for
+some profiles that don't differ between one profile and another, they are a
+property of the general process. For example how many random points to use
+in the monte-carlo integration, this value is fixed for all the
+profiles. The options described in this section are for configuring such
+properties.
@table @option
address@hidden --mode=STR
+Interpret the center position columns (@option{--ccol} in @ref{MakeProfiles
+catalog}) in image or WCS coordinates. This option thus accepts only two
+values: @option{img} and @option{wcs}. It is mandatory when a catalog is
+being used as input.
+
@item -r
@itemx --numrandom
The number of random points used in the central regions of the
@@ -14972,25 +14933,42 @@ default, the truncation column is considered to be in
units of the
radial parameters of the profile (@option{--rcol}). Read it as
`t-unit-in-p' for `truncation unit in pixels'.
address@hidden -X INT,INT
address@hidden --shift=INT,INT
-Shift all the profiles and enlarge the image along each dimension. To
-better understand this option, please see @mymath{n} in @ref{If convolving
-afterwards}. This is useful when you want to convolve the image
-afterwards. If you are using an external PSF, be sure to oversample it to
-the same scale used for creating the mock images. If a background image is
-specified, any possible value to this option is ignored.
address@hidden -f
address@hidden --mforflatpix
+When making fixed value profiles (flat and circumference, see
address@hidden'), don't use the value in the column specified by
address@hidden' as the magnitude. Instead use it as the exact value that
+all the pixels of these profiles should have. This option is irrelevant for
+other types of profiles. This option is very useful for creating masks, or
+labeled regions in an image. Any integer, or floating point value can used
+in this column with this option, including @code{NaN} (or address@hidden', or
address@hidden', case is irrelevant), and infinities (@code{inf}, @code{-inf},
+or @code{+inf}).
address@hidden -c
address@hidden --prepforconv
-Shift all the profiles and enlarge the image based on half the width
-of the first Moffat or Gaussian profile in the catalog, considering
-any possible oversampling see @ref{If convolving
-afterwards}. @option{--prepforconv} is only checked and possibly
-activated if @option{--xshift} and @option{--yshift} are both zero
-(after reading the command-line and configuration files). If a
-background image is specified, any possible value to this option is
-ignored.
+For example, with this option if you set the value in the magnitude column
+(@option{--mcol}) to @code{NaN}, you can create an elliptical or circular
+mask over an image (which can be given as the argument), see @ref{Blank
+pixels}. Another useful application of this option is to create labeled
+elliptical or circular apertures in an image. To do this, set the value in
+the magnitude column to the label you want for this profile. This labeled
+image can then be used in combination with NoiseChisel's output (see
address@hidden output}) to do aperture photometry with MakeCatalog (see
address@hidden).
+
+Alternatively, if you want to mark regions of the image (for example with
+an elliptical circumference) and you don't want to use NaN values (as
+explained above) for some technical reason, you can get the minimum or
+maximum value in the image @footnote{The minimum will give a better result,
+because the maximum can be too high compared to most pixels in the image,
+making it harder to display.} using Arithmetic (see @ref{Arithmetic}), then
+use that value in the magnitude column along with this option for all the
+profiles.
+
+Please note that when using MakeProfiles on an already existing image, you
+have to set address@hidden'. Otherwise all the profiles will be
+scaled up based on the oversampling scale in your configuration files (see
address@hidden files}) unless you have accounted for oversampling in
+your catalog.
@item --magatpeak
The magnitude column in the catalog (see @ref{MakeProfiles catalog})
@@ -15021,6 +14999,36 @@ have to set @option{--oversample=1} otherwise after
resampling your profile
with Warp (see @ref{Warp}), the peak flux will be different.
@end cartouche
address@hidden -X INT,INT
address@hidden --shift=INT,INT
+Shift all the profiles and enlarge the image along each dimension. To
+better understand this option, please see @mymath{n} in @ref{If convolving
+afterwards}. This is useful when you want to convolve the image
+afterwards. If you are using an external PSF, be sure to oversample it to
+the same scale used for creating the mock images. If a background image is
+specified, any possible value to this option is ignored.
+
address@hidden -c
address@hidden --prepforconv
+Shift all the profiles and enlarge the image based on half the width
+of the first Moffat or Gaussian profile in the catalog, considering
+any possible oversampling see @ref{If convolving
+afterwards}. @option{--prepforconv} is only checked and possibly
+activated if @option{--xshift} and @option{--yshift} are both zero
+(after reading the command-line and configuration files). If a
+background image is specified, any possible value to this option is
+ignored.
+
address@hidden -z FLT
address@hidden --zeropoint=FLT
+The zero-point magnitude of the image.
+
address@hidden -w FLT
address@hidden --circumwidth=FLT
+The width of the circumference if the profile is to be an elliptical
+circumference or annulus. See the explanations for this type of profile in
address@hidden
+
@item -R
@itemx --replace
Do not add the pixels of each profile over the background (possibly crowded
@@ -15045,6 +15053,43 @@ profile. However, when using flat profiles with the
address@hidden' option, you should be careful not to give a
@code{0.0} value as the flat profile's pixel value.
address@hidden table
+
address@hidden MakeProfiles output dataset, MakeProfiles log file, MakeProfiles
profile settings, Invoking astmkprof
address@hidden MakeProfiles output dataset
+MakeProfiles takes an input catalog uses basic properties that are defined
+there to build a dataset, for example a 2D image containing the profiles in
+the catalog. In @ref{MakeProfiles catalog} and @ref{MakeProfiles profile
+settings}, the catalog and profile settings were discussed. The options of
+this section, allow you to configure the output dataset (or the canvas that
+will host the built profiles).
+
address@hidden @option
+
address@hidden -k STR
address@hidden --background=STR
+A background image FITS file to build the profiles on. The extension that
+contains the image should be specified with the @option{--backhdu} option,
+see below. When a background image is specified, it will be used to derive
+all the information about the output image. Hence, the following options
+will be ignored: @option{--naxis}, @option{--oversample}, @option{--crpix},
address@hidden (generally, all other WCS related parameters) and the
+output's data type (see @option{--type} in @ref{Input output options}).
+
+The image will act like a canvas to build the profiles on: profile pixel
+values will be summed with the background image pixel values. With the
address@hidden option you can disable this behavior and replace the
+profile pixels with the background pixels. If you want to use all the image
+information above, except for the pixel values (you want to have a blank
+canvas to build the profiles on, based on an input image), you can call
address@hidden, to set all the input image's pixels to zero before
+starting to build the profiles over it (this is done in memory after
+reading the input, so nothing will happen to your input file).
+
address@hidden -B STR/INT
address@hidden --backhdu=STR/INT
+The header data unit (HDU) of the file given to @option{--background}.
+
@item -C
@itemx --clearcanvas
When an input image is specified (with the @option{--background} option,
@@ -15059,132 +15104,112 @@ catalog (see @ref{MakeCatalog}). In other cases,
you might have modeled the
objects in an image and want to create them on the same frame, but without
the original pixel values.
address@hidden -w FLT
address@hidden --circumwidth=FLT
-The width of the circumference if the profile is to be an elliptical
-circumference or annulus. See the explanations for this type of profile in
address@hidden
-
address@hidden -z FLT
address@hidden --zeropoint=FLT
-The zero-point magnitude of the image.
-
address@hidden table
address@hidden -E STR/INT,FLT[,FLT,[...]]
address@hidden --kernel=STR/INT,FLT[,FLT,[...]]
+Only build one kernel profile with the parameters given as the values to
+this option. The different values must be separated by a comma
+(@key{,}). The first value identifies the radial function of the profile,
+either through a string or through a number (see description of
address@hidden below). Each radial profile needs a different total number
+of parameters: S@'ersic and Moffat functions need 3 parameters: radial,
+S@'ersic index or Moffat @mymath{\beta}, and truncation radius. The
+Gaussian function needs two parameters: radial and truncation radius. The
+point function doesn't need any parameters and flat and circumference
+profiles just need one parameter (truncation radius).
address@hidden
-Catalog: The value to all of these options is considered to be a
-column number, where counting starts from zero.
+The PSF or kernel is a unique (and highly constrained) type of profile: the
+sum of its pixels must be one, its center must be the center of the central
+pixel (in an image with an odd number of pixels on each side), and commonly
+it is circular, so its axis ratio and position angle are one and zero
+respectively. Kernels are commonly necessary for various data analysis and
+data manipulation steps (for example see @ref{Convolve}, and
address@hidden Because of this it is inconvenient to define a catalog
+with one row and many zero valued columns (for all the non-necessary
+parameters). Hence, with this option, it is possible to create a kernel
+with MakeProfiles without the need to create a catalog. Here are some
+examples:
@table @option
address@hidden --kernel=moffat,3,2.8,5
+A Moffat kernel with FWHM of 3 pixels, @mymath{\beta=2.8} which is
+truncated at 5 times the FWHM.
address@hidden --mode=STR
-Interpret the center position columns in image or WCS coordinates. This
-option thus accepts only two values: @option{img} and @option{wcs}. It is
-mandatory when a catalog is being used.
-
address@hidden --ccol=STR/INT
-Center coordinate column for each dimension. This option must be called two
-times to define the center coordinates in an image. For example
address@hidden and @option{--ccol=DEC} (along with @option{--mode=wcs})
-will inform MakeProfiles to look into the catalog columns named @option{RA}
-and @option{DEC} for the Right Ascension and Declination of the profile
-centers.
-
address@hidden --fcol=INT/STR
-The functional form of the profile with one of the values below depending
-on the desired profile. The column can contain either the numeric codes
-(for example address@hidden') or string characters (for example
address@hidden'). The numeric codes are easier to use in scripts which
-generate catalogs with hundreds or thousands of profiles.
-
-The string format can be easier when the catalog is to be written/checked
-by hand/eye before running MakeProfiles. It is much more readable and
-provides a level of documentation. All Gnuastro's recognized table formats
-(see @ref{Recognized table formats}) accept string type columns. To have
-string columns in a plain text table/catalog, see @ref{Gnuastro text table
-format}.
-
address@hidden
address@hidden
-S@'ersic profile with address@hidden' or address@hidden'.
address@hidden
-Moffat profile with address@hidden' or address@hidden'.
address@hidden
-Gaussian profile with address@hidden' or address@hidden'.
address@hidden
-Point source with address@hidden' or address@hidden'.
address@hidden
-Flat profile with address@hidden' or address@hidden'.
address@hidden
-Circumference profile with address@hidden' or address@hidden'. A fixed
-value will be used for all pixels between the truncation radius
-(@mymath{r_t}) and @mymath{r_t-w} (@mymath{w} is the value to the
address@hidden).
address@hidden itemize
-
address@hidden --rcol=STR/INT
-The radius parameter of the profiles. Effective radius (@mymath{r_e}) if
-S@'ersic, FWHM if Moffat or Gaussian.
address@hidden --kernel=gaussian,2,3
+A Gaussian kernel with FWHM of 2 pixels and truncated at 3 times the FWHM.
address@hidden table
address@hidden --ncol=STR/INT
-The S@'ersic index (@mymath{n}) or Moffat @mymath{\beta}.
address@hidden -x INT,INT
address@hidden --naxis=INT,INT
+The number of pixels along each dimension axis of the output in FITS
+order. This is before over-sampling. For example if you call MakeProfiles
+with @option{--naxis=100,150 --oversample=5} (assuming no shift due for
+later convolution), then the final image size along the first axis will be
+500 by 750 pixels. Fractions are acceptable as values for each dimension,
+however, they must reduce to an integer, so @option{--naxis=150/3,300/3} is
+acceptable but @option{--naxis=150/4,300/4} is not.
address@hidden --pcol=STR/INT
-The position angle (in degrees) of the profiles relative to the first FITS
-axis (horizontal when viewed in SAO ds9).
+When viewing a FITS image in DS9, the first FITS dimension is in the
+horizontal direction and the second is vertical. As an example, the image
+created with the example above will have 500 pixels horizontally and 750
+pixels vertically.
address@hidden --qcol=STR/INT
-The axis ratio of the profiles (minor axis divided by the major axis).
+If a background image is specified, this option is ignored.
address@hidden --mcol=STR/INT
-The total pixelated magnitude of the profile within the truncation radius,
-see @ref{Profile magnitude}.
address@hidden -s INT
address@hidden --oversample=INT
+The scale to over-sample the profiles and final image. If not an odd
+number, will be added by one, see @ref{Oversampling}. Note that this
address@hidden will remain active even if an input image is
+specified. If your input catalog is based on the background image, be sure
+to set @option{--oversample=1}.
address@hidden --tcol=STR/INT
-The truncation radius of this profile. By default it is in units of the
-radial parameter of the profile (the value in the @option{--rcol} of the
-catalog). If @option{--tunitinp} is given, this value is interpreted in
-units of pixels (prior to oversampling) irrespective of the profile.
address@hidden --psfinimg
+Build the possibly existing PSF profiles (Moffat or Gaussian) in the
+catalog into the final image. By default they are built separately so
+you can convolve your images with them, thus their magnitude and
+positions are ignored. With this option, they will be built in the
+final image like every other galaxy profile. To have a final PSF in
+your image, make a point profile where you want the PSF and after
+convolution it will be the PSF.
address@hidden -f
address@hidden --mforflatpix
-When making fixed value profiles (flat and circumference, see
address@hidden'), don't use the value in the column specified by
address@hidden' as the magnitude. Instead use it as the exact value that
-all the pixels of these profiles should have. This option is irrelevant for
-other types of profiles. This option is very useful for creating masks, or
-labeled regions in an image. Any integer, or floating point value can used
-in this column with this option, including @code{NaN} (or address@hidden', or
address@hidden', case is irrelevant), and infinities (@code{inf}, @code{-inf},
-or @code{+inf}).
address@hidden -i
address@hidden --individual
address@hidden Individual profiles
address@hidden Build individual profiles
+If this option is called, each profile is created in a separate FITS
+file within the same directory as the output and the row number of the
+profile (starting from zero) in the name. The file for each row's
+profile will be in the same directory as the final combined image of
+all the profiles and will have the final image's name as a suffix. So
+for example if the final combined image is named
address@hidden/out/fromcatalog.fits}, then the first profile that will be
+created with this option will be named
address@hidden/out/0_fromcatalog.fits}.
-For example, with this option if you set the value in the magnitude column
-(@option{--mcol}) to @code{NaN}, you can create an elliptical or circular
-mask over an image (which can be given as the argument), see @ref{Blank
-pixels}. Another useful application of this option is to create labeled
-elliptical or circular apertures in an image. To do this, set the value in
-the magnitude column to the label you want for this profile. This labeled
-image can then be used in combination with NoiseChisel's output (see
address@hidden output}) to do aperture photometry with MakeCatalog (see
address@hidden).
+Since each image only has one full profile out to the truncation
+radius the profile is centered and so, only the sub-pixel position of
+the profile center is important for the outputs of this option. The
+output will have an odd number of pixels. If there is no oversampling,
+the central pixel will contain the profile center. If the value to
address@hidden is larger than unity, then the profile center is
+on any of the central @option{--oversample}'d pixels depending on the
+fractional value of the profile center.
-Alternatively, if you want to mark regions of the image (for example with
-an elliptical circumference) and you don't want to use NaN values (as
-explained above) for some technical reason, you can get the minimum or
-maximum value in the image @footnote{The minimum will give a better result,
-because the maximum can be too high compared to most pixels in the image,
-making it harder to display.} using Arithmetic (see @ref{Arithmetic}), then
-use that value in the magnitude column along with this option for all the
-profiles.
+If the fractional value is larger than half, it is on the bottom half
+of the central region. This is due to the FITS definition of a real
+number position: The center of a pixel has fractional value
address@hidden so each pixel contains these fractions: .5 -- .75 -- .00
+(pixel center) -- .25 -- .5.
-Please note that when using MakeProfiles on an already existing image, you
-have to set address@hidden'. Otherwise all the profiles will be
-scaled up based on the oversampling scale in your configuration files (see
address@hidden files}) unless you have accounted for oversampling in
-your catalog.
address@hidden -m
address@hidden --nomerged
+Don't make a merged image. By default after making the profiles, they are
+added to a final image with side lengths specified by @option{--naxis}if
+they overlap with it.
@end table
+
@noindent
The options below can be used to define the world coordinate system (WCS)
properties of the MakeProfiles outputs. The option names are delibarately
@@ -15244,31 +15269,38 @@ later usage of them might cause trouble.
@end table
address@hidden MakeProfiles output, , MakeProfiles options, Invoking astmkprof
address@hidden MakeProfiles output
address@hidden MakeProfiles log file, , MakeProfiles output dataset, Invoking
astmkprof
address@hidden MakeProfiles log file
-Besides the final merged image of all the profiles or individual
-profiles that can be built based on the input options, MakeProfiles
-will also create a log file in the current directory (where you run
-MockProfiles). The values for each column are explained in the first
-few commented (starting with @command{#} character). The log file
-includes the following information:
+Besides the final merged dataset of all the profiles, or the individual
+datasets (see @ref{MakeProfiles output dataset}), if the @option{--log}
+option is called MakeProfiles will also create a log file in the current
+directory (where you run MockProfiles). See @ref{Common options} for a full
+description of @option{--log} and other options that are shared between all
+Gnuastro programs. The values for each column are explained in the first
+few commented lines of the log file (starting with @command{#}
+character). Here is a more complete description.
@itemize
@item
-The total magnitude of the profile in the image. This will be
-different from your input magnitude if the profile was not completely
-in the image.
+An ID (row number of profile in input catalog).
+
address@hidden
+The total magnitude of the profile in the output dataset. When the profile
+does not completely overlap with the output dataset, this will be different
+from your input magnitude.
@item
The number of pixels (in the oversampled image) which used Monte Carlo
-integration and not the central pixel value.
+integration and not the central pixel value, see @ref{Sampling from a
+function}.
@item
The fraction of flux in the Monte Carlo integrated pixels.
@item
-If an individual image was created or not.
+If an individual image was created, this column will have a value of
address@hidden, otherwise it will have a value of @code{0}.
@end itemize
@@ -17920,9 +17952,9 @@ acceptable values to this element are defined in
@ref{Table input
output}. Based on C's @code{printf} standards.
@item gal_data_t *next
-Through this pointer, you can link a @code{gal_data_t} with other related
-datasets, for example the different columns in a dataset each have one
address@hidden associate with them and they are linked to each other
+Through this pointer, you can link a @code{gal_data_t} with other datasets
+related datasets, for example the different columns in a dataset each have
+one @code{gal_data_t} associate with them and they are linked to each other
using this element. There are several functions described below to
facilitate using @code{gal_data_t} as a linked list. See @ref{Linked lists}
for more on these wonderful high-level constructs.
@@ -18024,7 +18056,7 @@ memory or it is used in multiple datasets, be sure to
set it to @code{NULL}
not have any zero values (a dimension of length zero is not defined).
@end deftypefun
address@hidden {void *} gal_data_alloc (void @code{*array}, uint8_t
@code{type}, size_t @code{ndim}, size_t @code{*dsize}, struct wcsprm
@code{*wcs}, int @code{clear}, size_t @code{minmapsize}, char @code{*name},
char @code{*unit}, char @code{*comment})
address@hidden {gal_data_t *} gal_data_alloc (void @code{*array}, uint8_t
@code{type}, size_t @code{ndim}, size_t @code{*dsize}, struct wcsprm
@code{*wcs}, int @code{clear}, size_t @code{minmapsize}, char @code{*name},
char @code{*unit}, char @code{*comment})
Dynamically allocate a @code{gal_data_t} and initialize it will all the
given values. See the description of @code{gal_data_initialize} and
@@ -18036,9 +18068,10 @@ the dataset, be sure to clean up all the allocated
spaces with
@end deftypefun
@deftypefun void gal_data_free_contents (gal_data_t @code{*data})
-Free all the address@hidden pointers in @code{gal_data_t}, for a complete
-description of the @code{gal_data_t} contents, see @ref{Generic data
-container}.
+Free all the address@hidden pointers in @code{gal_data_t}. If @code{data}
+is actually a tile (@code{data->block!=NULL}, see @ref{Tessellation
+library}), then @code{tile->array} is not freed. For a complete description
+of @code{gal_data_t} and its contents, see @ref{Generic data container}.
@end deftypefun
@deftypefun void gal_data_free (gal_data_t @code{*data})
@@ -20488,13 +20521,27 @@ operation will be done on @code{numthreads} threads.
@deffn {Function-like macro} GAL_TILE_PARSE_OPERATE (@code{IN}, @code{OTHER},
@code{PARSE_OTHER}, @code{CHECK_BLANK}, @code{OP})
-Parse over @code{IN} (which can be a tile or a fully allocated block of
-memory) and do the @code{OP} operation on it (can be any combination of C
-expressions). If @code{OTHER!=NULL}, this macro will allow access to its
-element(s) and it can optionally be parsed while parsing over
address@hidden You can use this to parse the same region over two arrays. The
-input arguments are (the expected types of each argument are also written
-here):
+Parse @code{IN} (which can be a tile or a fully allocated block of memory)
+and do the @code{OP} operation on it. @code{OP} can be any combination of C
+expressions. If @code{OTHER!=NULL}, @code{OTHER} will be interpretted as a
+dataset and this macro will allow access to its element(s) and it can
+optionally be parsed while parsing over @code{IN}.
+
+If @code{OTHER} is a fully allocated block of memory (not a tile), then the
+same region that is covered by @code{IN} within its own block will be
+parsed (the same starting pixel with the same number of pixels in each
+dimension). Hence, in this case, the blocks of @code{OTHER} and @code{IN}
+must have the same size. When @code{OTHER} is a tile it must have the same
+size as @code{IN} and parsing will start from its starting element/pixel.
+Also, the respective allocated blocks of @code{OTHER} and @code{IN} (if
+different) may have different sizes. Using @code{OTHER} (along with
address@hidden), this funciton-like macro will thus enable you to parse
+and define your own operation on two fixed size regions in one or two
+blocks of memory. In the latter case, they may have different numeric
+datatypes, see @ref{Numeric data types}).
+
+The input arguments to this macro are explained below, the expected type of
+each argument are also written following the argument name:
@table @code
@item IN (gal_data_t)
@@ -20504,8 +20551,12 @@ Input dataset, this can be a tile or an allocated
block of memory.
Dataset (@code{gal_data_t}) to parse along with @code{IN}. It can be
@code{NULL}. In that case, @code{o} (see description of @code{OP} below)
will be @code{NULL} and should not be used. If @code{PARSE_OTHER} is zero,
-the size of this dataset is irrelevant. Otherwise, it has to have the same
-size as the allocated block of @code{IN}.
+only its first element will be used and the size of this dataset is
+irrelevant.
+
+When @code{OTHER} is a block of memory, it has to have the same size as the
+allocated block of @code{IN}. When its a tile, it has to have the same size
+as @code{IN}.
@item PARSE_OTHER (int)
Parse the other dataset along with the input. When this is non-zero and
@@ -20556,15 +20607,15 @@ Blank value in the type of @code{INPUT}.
@end table
@end table
-You can use a given tile (@code{tile}) on a dataset that it was not
-initialized with (but has the same size, let's call it @code{new}) with the
+You can use a given tile (@code{tile} on a dataset that it was not
+initialized with but has the same size, let's call it @code{new}) with the
following steps:
@example
void *tarray;
gal_data_t *tblock;
-/* `tile->block' must corrected AFTER `tile->array' */
+/* `tile->block' must be corrected AFTER `tile->array'. */
tarray = tile->array;
tblock = tile->block;
tile->array = gal_tile_block_relative_to_other(tile, new);
@@ -20604,15 +20655,15 @@ faketile->size = tile->size;
faketile->dsize = tile->dsize;
faketile->array = gal_tile_block_relative_to_other(tile, new);
-// Do your processing....
+/* Do your processing.... in a loop (over many tiles). */
GAL_TILE_PARSE_OPERATE(tile, faketile, 1, 1, @{
YOUR_PROCESSING_EXPRESSIONS;
@});
-// Clean up.
-bintile->array=NULL;
-bintile->dsize=NULL;
-gal_data_free(bintile);
+/* Clean up (outside the loop). */
+faketile->array=NULL;
+faketile->dsize=NULL;
+gal_data_free(faketile);
@end example
@end deffn
@@ -20860,28 +20911,37 @@ declared in @file{gnuastro/box.h}. All coordinates in
this header are in
the FITS format (first axis is the horizontal and the second axis is
vertical).
address@hidden void gal_box_ellipse_in_box (double @code{a}, double @code{b},
double @code{theta_rad}, long @code{*width})
address@hidden void gal_box_bound_ellipse (double @code{a}, double @code{b},
double @code{theta_deg}, long @code{*width})
Any ellipse can be enclosed into a rectangular box. The purpose of this
-function is to give the height and width of that box. @code{a} is the
-ellipse major axis, @code{b} is the minor axis, @code{theta_rad} is the
-position angle in radians. The @code{width} array will contain the output
-size in long integer type. @code{width[0]}, and @code{width[1]} are the
-number of pixels along the first and second FITS axis.
+function is to give the height and width of that box assuming the center of
+the ellipse is in the box center. @code{a} is the ellipse major axis,
address@hidden is the minor axis, @code{theta_deg} is the position angle in
+degrees. The @code{width} array will contain the output size in long
+integer type. @code{width[0]}, and @code{width[1]} are the number of pixels
+along the first and second FITS axis. Since the ellipse center is assumed
+to be in the center of the box, all the values in @code{width} will be an
+odd integer.
@end deftypefun
address@hidden void gal_box_border_from_center (double @code{xc}, double
@code{yc}, long @code{*width}, long @code{*fpixel}, long @code{*lpixel})
-Given the center (@code{xc} and @code{yc}) and width (two element array) of a
-box, return the coordinates of the first @code{fpixel} and last @code{lpixel}
-pixels (both are two element arrays.
address@hidden void gal_box_border_from_center (double @code{center}, size_t
@code{ndim}, long @code{*width}, long @code{*fpixel}, long @code{*lpixel})
+Given the center coordinates in @code{center} and the @code{width} (along
+each dimension) of a box, return the coordinates of the first
+(@code{fpixel}) and last (@code{lpixel}) pixels. All arrays must have
address@hidden elements (one for each dimension).
@end deftypefun
address@hidden int gal_box_overlap (long @code{*naxes}, long @code{*fpixel_i},
long @code{*lpixel_i}, long @code{*fpixel_o}, long @code{*lpixel_o})
-We have an image of size @code{naxes} and want to get the overlap of the
-image with a box. This function will return 1 if there is an overlap and 0
-if there isn't. The input and output box are specified by their first and
-last pixels. When there is an overlap, the coordinates of the first and
-last pixels of the overlap will be put in @code{fpixel_o} and
address@hidden
address@hidden int gal_box_overlap (long @code{*naxes}, long @code{*fpixel_i},
long @code{*lpixel_i}, long @code{*fpixel_o}, long @code{*lpixel_o}, size_t
@code{ndim})
+An @code{ndim}-dimensional dataset of size @code{naxes} (along each
+dimension, in FITS order) and a box with first and last (inclusive)
+coordinate of @code{fpixel_i} and @code{lpixel_i} is given. This box
+doesn't necessarily have to lie within the dataset, it can be outside of
+it, or only patially overlap. This function will change the values of
address@hidden and @code{lpixel_i} to exactly cover the overlap in the
+input dataset's coordinates.
+
+This function will return 1 if there is an overlap and 0 if there
+isn't. When there is an overlap, the coordinates of the first and last
+pixels of the overlap will be put in @code{fpixel_o} and @code{lpixel_o}.
@end deftypefun
diff --git a/lib/box.c b/lib/box.c
index ae5e708..2b3250b 100644
--- a/lib/box.c
+++ b/lib/box.c
@@ -1,5 +1,5 @@
/*********************************************************************
-overlap -- Find the overlap of a region and an image.
+Box -- Define bounding and overlapping boxes.
This is part of GNU Astronomy Utilities (Gnuastro) package.
Original author:
@@ -64,20 +64,20 @@ along with Gnuastro. If not, see
<http://www.gnu.org/licenses/>.
and you will find the distance (about the center of the ellipse
that encloses the whole ellipse. */
void
-gal_box_ellipse_in_box(double a, double b, double theta_rad, long *width)
+gal_box_bound_ellipse(double a, double b, double theta_deg, long *width)
{
- double t_x, t_y, max_x, max_y;
- t_x=atan(b/a*tan(theta_rad));
- t_y=atan(-1*b/a/tan(theta_rad));
+ double t_r=theta_deg*M_PI/180;
+ double max_x, max_y, ct=cos(t_r), st=sin(t_r);
+ double t_x=atan(b/a*tan(t_r)), t_y=atan(-1.0f*b/a/tan(t_r));
- max_x=a*cos(t_x)*cos(theta_rad)+b*sin(t_x)*sin(theta_rad);
- max_y=-1*a*cos(t_y)*sin(theta_rad)+b*sin(t_y)*cos(theta_rad);
+ /* Calculate the maxima along each direction. */
+ max_x = a*cos(t_x)*ct + b*sin(t_x)*st;
+ max_y = -1*a*cos(t_y)*st + b*sin(t_y)*ct;
/* max_x and max_y are calculated from the center of the ellipse. We
want the final height and width of the box enclosing the
ellipse. So we have to multiply them by two, then take one from
- them (for the center).
- */
+ them (for the center). */
width[0]=2*( (size_t)fabs(max_x)+1 ) + 1;
width[1]=2*( (size_t)fabs(max_y)+1 ) + 1;
}
@@ -129,19 +129,19 @@ gal_box_border_from_center(double *center, size_t ndim,
long *width,
-/* Problem to solve: We have set the first and last pixels in an input
- image (fpixel_i[2] and lpixel_i[2]). But those first and last
- pixels don't necessarily have to lie within the image, they can be
- outside of it or patially overlap with it. So the job of this
- function is to correct for such situations and find the starting
+/* Problem to solve: We have set the first and last pixels of a box in an
+ input image (fpixel_i[2] and lpixel_i[2]). But those first and last
+ pixels don't necessarily lie within the image's boundaries. They can be
+ outside of it or patially overlap with it (see examples below). The job
+ of this function is to corret for such situations and find the starting
and ending points of any overlap.
- It is assumed that your output (overlap) image's first pixel lies
- right ontop of the fpixel_i[0] in the input image. But since
- fpixel_i might be outside of the image, in this function we find
- the fpixel_o[2] and lpixel_o[2] in the overlap image coordinates
- that overlap with the input image. So the values of all four points
- might change after this function.
+ It is assumed that your output (overlap) image's first pixel lies right
+ ontop of the fpixel_i[0] in the input image. But since fpixel_i might be
+ outside of the image, in this function we find the fpixel_o[2] and
+ lpixel_o[2] in the overlap image coordinates that overlap with the input
+ image. So the values of all four points might change after this
+ function.
Before:
=======
diff --git a/lib/data.c b/lib/data.c
index 68178b2..ba7ff40 100644
--- a/lib/data.c
+++ b/lib/data.c
@@ -434,7 +434,7 @@ gal_data_free_contents(gal_data_t *data)
free(data->mmapname);
}
else
- if(data->array) free(data->array);
+ if(data->array && data->block==NULL) free(data->array);
data->array=NULL;
}
diff --git a/lib/gnuastro/box.h b/lib/gnuastro/box.h
index a1aa764..7d4add5 100644
--- a/lib/gnuastro/box.h
+++ b/lib/gnuastro/box.h
@@ -1,5 +1,5 @@
/*********************************************************************
-overlap -- Find the overlap of a region and an image.
+Box -- Define bounding and overlapping boxes.
This is part of GNU Astronomy Utilities (Gnuastro) package.
Original author:
@@ -52,7 +52,7 @@ __BEGIN_C_DECLS /* From C++ preparations */
*/
void
-gal_box_ellipse_in_box(double a, double b, double theta_rad, long *width);
+gal_box_bound_ellipse(double a, double b, double theta_rad, long *width);
void
gal_box_border_from_center(double *center, size_t ndim, long *width,
diff --git a/lib/gnuastro/tile.h b/lib/gnuastro/tile.h
index 0d17484..2809b23 100644
--- a/lib/gnuastro/tile.h
+++ b/lib/gnuastro/tile.h
@@ -71,6 +71,8 @@ gal_tile_series_from_minmax(gal_data_t *block, size_t
*minmax, size_t number);
+
+
/***********************************************************************/
/************** Allocated block **********************/
/***********************************************************************/
@@ -96,6 +98,8 @@ gal_tile_block_blank_flag(gal_data_t *tile_ll, size_t
numthreads);
+
+
/***********************************************************************/
/************** Tile full dataset ********************/
/***********************************************************************/
@@ -177,40 +181,90 @@ gal_tile_full_free_contents(struct
gal_tile_two_layer_params *tl);
`GAL_TILE_PARSE_OPERATE'), so some variables (basic definitions) that
are already defined in `GAL_TILE_PARSE_OPERATE' re-defined here. */
#define GAL_TILE_PO_OISET(IT, OT, IN, OTHER, PARSE_OTHER, CHECK_BLANK, OP) { \
+ IT *i=IN->array; \
+ gal_data_t *tpo_other=OTHER; /* `OTHER' may be NULL. */ \
+ gal_data_t *tpo_oblock = OTHER ? gal_tile_block(OTHER) : NULL; \
+ \
+ size_t tpo_s_e_i_junk[2]={0,0}; \
+ IT b, *tpo_st=NULL, *tpo_f=i+IN->size; \
+ size_t tpo_i_increment=0, tpo_num_i_inc=1; \
+ size_t tpo_o_increment=0, tpo_num_o_inc=1; \
int tpo_parse_other=(OTHER && PARSE_OTHER); \
- size_t tpo_increment=0, tpo_num_increment=1; \
- gal_data_t *tpo_other_w=OTHER; /* `OTHER' may be NULL. */ \
gal_data_t *tpo_iblock = gal_tile_block(IN); \
- IT b, *tpo_st=NULL, *i=IN->array, *tpo_f=i+IN->size; \
- OT *tpo_ost=NULL, *o = tpo_other_w ? tpo_other_w->array : NULL; \
- gal_data_t *tpo_oblock = OTHER ? gal_tile_block(OTHER) : NULL; \
+ OT *tpo_ost=NULL, *o = tpo_other ? tpo_other->array : NULL; \
int tpo_hasblank = CHECK_BLANK ? gal_blank_present(IN, 0) : 0; \
size_t tpo_s_e_i[2]={0,tpo_iblock->size-1}; /* -1: this is INCLUSIVE */ \
\
+ \
+ /* A small sanity check: if `OTHER' is given, and it is a block, */ \
+ /* then it must have the same size as `IN's block. On the other */ \
+ /* hand, when `OTHER' is a tile, its must have `IN's size. */ \
+ if( tpo_parse_other ) \
+ { \
+ if( OTHER==tpo_oblock ) /* `OTHER' is a block. */ \
+ { \
+ if(gal_data_dsize_is_different(tpo_iblock, tpo_oblock) ) \
+ { \
+ /* `error' function, is a GNU extension, see above. */ \
+ fprintf(stderr, "GAL_TILE_PO_OISET: when " \
+ "`PARSE_OTHER' is non-zero, the allocated " \
+ "block size of `IN' and `OTHER' must be " \
+ "equal, but they are not: %zu and %zu " \
+ "elements respectively\n", tpo_iblock->size, \
+ tpo_oblock->size); \
+ exit(EXIT_FAILURE); \
+ } \
+ } \
+ else \
+ if(gal_data_dsize_is_different(IN, OTHER) ) \
+ { \
+ /* The `error' function, is a GNU extension and this is */ \
+ /* a header, not a library which the user has to compile */ \
+ /* every time (on their own system). */ \
+ fprintf(stderr, "GAL_TILE_PO_OISET: when " \
+ "`PARSE_OTHER' is non-zero, the sizes of `IN' " \
+ "and `OTHER' must be equal (in all " \
+ "dimensions), but they are not: %zu and %zu " \
+ "elements respectively\n", IN->size, \
+ tpo_other->size); \
+ exit(EXIT_FAILURE); \
+ } \
+ } \
+ \
+ \
/* Write the blank value for the input type into `b'. */ \
gal_blank_write(&b, tpo_iblock->type); \
\
- /* If this is a tile, not a full block. */ \
+ \
+ /* If this is a tile, not a full block, then we need to set the */ \
+ /* starting pointers (`tpo_st' and `tpo_ost'). The latter needs */ \
+ /* special attention: if it is a block, then we will use the */ \
+ /* the same starting element as the input tile. If `OTHER' is a */ \
+ /* tile, then use its own starting position (recall that we have */ \
+ /* already made sure that `IN' and `OTHER' have the same size. */ \
if(IN!=tpo_iblock) \
{ \
tpo_st = gal_tile_start_end_ind_inclusive(IN, tpo_iblock, \
- tpo_s_e_i); \
+ tpo_s_e_i); \
if( tpo_parse_other ) \
- tpo_ost = ( (OT *)(tpo_oblock->array) \
- + ( tpo_st - (IT *)(tpo_iblock->array) ) ); \
+ tpo_ost = ( OTHER==tpo_oblock \
+ ? ( (OT *)(tpo_oblock->array) \
+ + ( tpo_st - (IT *)(tpo_iblock->array) ) ) \
+ : gal_tile_start_end_ind_inclusive(tpo_other, \
+ tpo_oblock, \
+ tpo_s_e_i_junk) ); \
} \
\
+ \
/* Go over contiguous patches of memory. */ \
- while( tpo_s_e_i[0] + tpo_increment <= tpo_s_e_i[1] ) \
+ while( tpo_s_e_i[0] + tpo_i_increment <= tpo_s_e_i[1] ) \
{ \
- \
- /* If we are on a tile, reset `i' and `f'. Also, if there */ \
- /* is more than one element in `OTHER', then set that. Note */ \
- /* that it is upto the caller to increment `o' in `OP'. */ \
+ /* If we are on a tile, reset `i' and `o'. */ \
if(IN!=tpo_iblock) \
{ \
- tpo_f = ( i = tpo_st + tpo_increment ) + IN->dsize[IN->ndim-1]; \
- if(tpo_parse_other) o = tpo_ost + tpo_increment; \
+ tpo_f = ( ( i = tpo_st + tpo_i_increment ) \
+ + IN->dsize[IN->ndim-1] ); \
+ if(tpo_parse_other) o = tpo_ost + tpo_o_increment; \
} \
\
/* Do the operation depending the nature of the blank value. */ \
@@ -232,17 +286,32 @@ gal_tile_full_free_contents(struct
gal_tile_two_layer_params *tl);
else \
do { {OP;} if(tpo_parse_other) ++o;} while(++i<tpo_f);\
\
- \
/* Set the incrementation. On a fully allocated iblock (when */ \
/* `IN==tpo_iblock'), we have already gone through the whole */ \
/* array, so we'll set the incrementation to the size of the */ \
- /* while block which will stop the `while' loop above. On a */ \
+ /* whole block. This will stop the `while' loop above. On a */ \
/* tile, we need to increment to the next contiguous patch */ \
/* of memory to continue parsing this tile. */ \
- tpo_increment += ( IN==tpo_iblock ? tpo_iblock->size \
- : gal_tile_block_increment(tpo_iblock, IN->dsize, \
- tpo_num_increment++, \
- NULL) ); \
+ tpo_i_increment += ( IN==tpo_iblock \
+ ? tpo_iblock->size \
+ : gal_tile_block_increment(tpo_iblock, \
+ IN->dsize, \
+ tpo_num_i_inc++, \
+ NULL) ); \
+ \
+ /* Similarly, increment the other array if necessary. Like */ \
+ /* the above, when `OTHER' is a full block, we'll just use */ \
+ /* the same increment as `IN'. Otherwise, when `OTHER' is a */ \
+ /* tile, calculate its increment based on its own block. */ \
+ if(tpo_parse_other) \
+ { \
+ if(OTHER==tpo_oblock) tpo_o_increment=tpo_i_increment; \
+ else \
+ tpo_o_increment += gal_tile_block_increment(tpo_oblock, \
+ tpo_other->dsize, \
+ tpo_num_o_inc++, \
+ NULL); \
+ } \
} \
\
/* This is done in case the caller doesn't need `o' to avoid */ \
@@ -302,23 +371,9 @@ gal_tile_full_free_contents(struct
gal_tile_two_layer_params *tl);
pixel/element of the input). See the documentation for more on this
macro and some examples. */
#define GAL_TILE_PARSE_OPERATE(IN, OTHER, PARSE_OTHER, CHECK_BLANK, OP) { \
- int tpo_parse_other=(OTHER && PARSE_OTHER); \
gal_data_t *tpo_iblock = gal_tile_block(IN); \
gal_data_t *tpo_oblock = OTHER ? gal_tile_block(OTHER) : NULL; \
\
- /* A small sanity check. */ \
- if( tpo_parse_other \
- && gal_data_dsize_is_different(tpo_iblock, tpo_oblock) ) \
- { \
- /* The `error' function, is a GNU extension. */ \
- fprintf(stderr, "GAL_TILE_PARSE_OPERATE: when `PARSE_OTHER' is "\
- "non-zero, the allocated block size of `IN' and " \
- "`OTHER' must be equal, but they are not: %zu and %zu " \
- "elements respectively)", tpo_iblock->size, \
- tpo_oblock->size); \
- exit(EXIT_FAILURE); \
- } \
- \
/* First set the OTHER type. */ \
if(OTHER) \
switch(tpo_oblock->type) \
diff --git a/lib/tile.c b/lib/tile.c
index 6ecbbad..5457375 100644
--- a/lib/tile.c
+++ b/lib/tile.c
@@ -348,9 +348,9 @@ size_t
gal_tile_block_increment(gal_data_t *block, size_t *tsize,
size_t num_increment, size_t *coord)
{
- size_t increment;
size_t n=block->ndim;
size_t *b=block->dsize, *t=tsize;
+ size_t increment=GAL_BLANK_SIZE_T;
if(n>3)
error(EXIT_FAILURE, 0, "%s: currently only implemented for at most 3 "
@@ -358,6 +358,7 @@ gal_tile_block_increment(gal_data_t *block, size_t *tsize,
switch(n)
{
+ /* A zero-dimensional dataset is not defined. */
case 0:
error(EXIT_FAILURE, 0, "%s: zero dimensional input is not acceptable",
__func__);
@@ -374,18 +375,17 @@ gal_tile_block_increment(gal_data_t *block, size_t *tsize,
if(coord) ++coord[0];
break;
- /* Higher dimensions. */
- default:
- if(num_increment % t[n-2])
+ /* 3D: The increment depends on which dimension we are reaching. */
+ case 3:
+ if(num_increment % t[1])
{
- increment=b[n-1];
- if(coord) ++coord[n-2];
+ increment = b[2];
+ if(coord) ++coord[1];
}
else
{
- increment=(b[n-2] * b[n-1]) - ( (t[n-2]-1) * b[n-1] );
- ++coord[n-3];
- if(coord) coord[n-2]=coord[n-1]=0;
+ increment=(b[1] * b[2]) - ( (t[1]-1) * b[2] );
+ if(coord) { ++coord[0]; coord[1]=coord[2]=0; }
}
break;
}
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gnuastro-commits] master e03e9ea: Corrections in library and manual,
Mohammad Akhlaghi <=