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 MakeProfiles catalog and 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).
A background image FITS file to build the profiles on. The extension that contains the image should be specified with the --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: --mergedsize, --oversample, --crpix, --crval (generally, all other WCS related parameters) and the output’s data type (see --type in Input/Output options).
The background 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 --replace 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 --clearcanvas, 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).
The header data unit (HDU) of the file given to --background.
When an input image is specified (with the --background option, set all its pixels to 0.0 immediately after reading it into memory. Effectively, this will allow you to use all its properties (described under the --background option), without having to worry about the pixel values.
--clearcanvas can come in handy in many situations, for example, if you want to create a labeled image (segmentation map) for creating a catalog (see 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.
Only build one kernel profile with the parameters given as the values to this option. The different values must be separated by a comma (,). The first value identifies the radial function of the profile, either through a string or through a number (see description of --fcol in MakeProfiles catalog). Each radial profile needs a different total number of parameters: Sérsic and Moffat functions need 3 parameters: radial, Sérsic index or Moffat \(\beta\), and truncation radius. The Gaussian function needs two parameters: radial and truncation radius. The point function does not 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 Convolve, and NoiseChisel. 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:
A Moffat kernel with FWHM of 3 pixels, \(\beta=2.8\) which is truncated at 5 times the FWHM.
A circular Gaussian kernel with FWHM of 2 pixels and truncated at 3 times the FWHM.
This option may also be used to create a 3D kernel.
To do that, two small modifications are necessary: add a -3d (or -3D) to the profile name (for example, moffat-3d) and add a number (axis-ratio along the third dimension) to the end of the parameters for all profiles except point.
The main reason behind providing an axis ratio in the third dimension is that in 3D astronomical datasets, commonly the third dimension does not have the same nature (units/sampling) as the first and second.
For example, in IFU (optical) or Radio data cubes, the first and second dimensions are commonly spatial/angular positions (like RA and Dec) but the third dimension is wavelength or frequency (in units of Angstroms for Herz). Because of this different nature (which also affects the processing), it may be necessary for the kernel to have a different extent in that direction.
If the 3rd dimension axis ratio is equal to \(1.0\), then the kernel will be a spheroid. If it is smaller than \(1.0\), the kernel will be button-shaped: extended less in the third dimension. However, when it islarger than \(1.0\), the kernel will be bullet-shaped: extended more in the third dimension. In the latter case, the radial parameter will correspond to the length along the 3rd dimension. For example, let’s have a look at the two examples above but in 3D:
An ellipsoid Moffat kernel with FWHM of 3 pixels, \(\beta=2.8\) which is truncated at 5 times the FWHM. The ellipsoid is circular in the first two dimensions, but in the third dimension its extent is half the first two.
A spherical Gaussian kernel with FWHM of 2 pixels and truncated at 3 times the FWHM.
Of course, if a specific kernel is needed that does not fit the constraints imposed by this option, you can always use a catalog to define any arbitrary kernel. Just call the --individual and --nomerged options to make sure that it is built as a separate file (individually) and no “merged” image of the input profiles is created.
The number of pixels along each axis of the output, in FITS order. This is before over-sampling. For example, if you call MakeProfiles with --mergedsize=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 --mergedsize=150/3,300/3 is acceptable but --mergedsize=150/4,300/4 is not.
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.
If a background image is specified, this option is ignored.
The scale to over-sample the profiles and final image. If not an odd number, will be added by one, see Oversampling. Note that this --oversample will remain active even if an input image is specified. If your input catalog is based on the background image, be sure to set --oversample=1.
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.
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 ./out/fromcatalog.fits, then the first profile that will be created with this option will be named ./out/0_fromcatalog.fits.
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 --oversample is larger than unity, then the profile center is on any of the central --oversample’d pixels depending on the fractional value of the profile center.
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 \(0.00\) so each pixel contains these fractions: .5 – .75 – .00 (pixel center) – .25 – .5.
Do not make a merged image. By default after making the profiles, they are added to a final image with side lengths specified by --mergedsize if they overlap with it.
The options below can be used to define the world coordinate system (WCS) properties of the MakeProfiles outputs. The option names are deliberately chosen to be the same as the FITS standard WCS keywords. See Section 8 of Pence et al [2010] for a short introduction to WCS in the FITS standard233.
If you look into the headers of a FITS image with WCS for example, you will see all these names but in uppercase and with numbers to represent the dimensions, for example, CRPIX1 and PC2_1.
You can see the FITS headers with Gnuastro’s Fits program using a command like this: $ astfits -p image.fits.
If the values given to any of these options does not correspond to the number of dimensions in the output dataset, then no WCS information will be added. Also recall that if you use the --background option, all of these options are ignored. Such that if the image given to --background does not have any WCS, the output of MakeProfiles will also not have any WCS, even if these options are given234.
The pixel coordinates of the WCS reference point. Fractions are acceptable for the values of this option.
The WCS coordinates of the Reference point.
Fractions are acceptable for the values of this option.
The comma-separated values can either be in degrees (a single number), or sexagesimal (_h_m_ for RA, _d_m_ for Dec, or _:_:_ for both).
In any case, the final value that will be written in the CRVAL keyword will be a floating point number in degrees (according to the FITS standard).
The resolution (size of one data-unit or pixel in WCS units) of the non-oversampled dataset. Fractions are acceptable for the values of this option.
The PC matrix of the WCS rotation, see the FITS standard (link above) to better understand the PC matrix.
The units of each WCS axis, for example, deg.
Note that these values are part of the FITS standard (link above).
MakeProfiles will not complain if you use non-standard values, but later usage of them might cause trouble.
The type of each WCS axis, for example, RA---TAN and DEC--TAN.
Note that these values are part of the FITS standard (link above).
MakeProfiles will not complain if you use non-standard values, but later usage of them might cause trouble.
The world coordinate standard in FITS is a very beautiful and powerful concept to link/associate datasets with the outside world (other datasets). The description in the FITS standard (link above) only touches the tip of the ice-burg. To learn more please see Greisen and Calabretta [2002], Calabretta and Greisen [2002], Greisen et al. [2006], and Calabretta et al.
If you want to add profiles and WCS over the background image (to produce your output), you need more than one command: 1. You should use --mergedsize in MakeProfiles to manually set the output number of pixels equal to your desired background image (so the background is zero). In this mode, you can use these WCS-related options to define the WCS. 2. Then use Arithmetic to add the pixels of your mock image to the background (see Arithmetic.
JavaScript license information
GNU Astronomy Utilities 0.23 manual, July 2024.