Generating Images from the Command Line
Use the imgenerate program to generate images from the command line, which should be in your search path. If not, you need to install imengine or else run from a build/ subdirectory as ./imgenerate.
The following help is available via imengine --help:
-h [ --help ] Prints this info and exits. -o [ --output ] arg Output file for writing image data (defaults to stdout). --png Writes a 16-bit grayscale png image. --noninverted Any png image written will be non-inverted (default is inverted). --midpoint Uses the midpoint method for pixelization. --bilinear Uses bilinear interpolation for pixelization. --bicubic Uses bicubic interpolation for pixelization (this is the default). --slow Uses un-optimized discrete Fourier transforms. --fast Uses optimized fast Fourier transforms (default). -n [ --npixels ] arg (=48) Number of pixels per side for final square image. --dx arg (=0) Horizontal source shift. --dy arg (=0) Vertical source shift. --scale arg (=1) Pixel scale. --oversampling arg (=1) Divides each pixel into N x N subpixels. --margin arg (=0) Adds or subtracts a temporary margin when generating the image. --total arg (=1) Total pixel sum of generated image. --offset arg (=0) Amount to offset generated pixel values by. --gain arg (=0) Signal size per photon to use for generating Poisson fluctuations. --noiseRMS arg (=0) RMS of uncorrelated Gaussian noise to add to each pixel. --seed arg (=0) Random seed to use for generating noise (uses time of day if zero). --printsum Prints the pixel sum of the generated image. --src arg (=delta) Source model to use. --psf arg (=delta) PSF model to use.
The src and psf parameters specify the two flux density functions that will be convolved to generate the image. Each is specified by a string based on the same parser grammar (documented here). Dimensional parameters are generally in scaled pixel units, so their meaning depends on the chosen npixels and scale values: keep their product constant to generate images of the same flux density model at different resolutions.
By default, the generated image is output as numerical (floating point) pixel values to the screen. An NxN image produces N lines (y) of N numbers (x). Use the --output option to redirect this output to a file.
If you installed imengine with png support, you can output a 16-bit grayscale image file using either the --png option or else using an output filename with the extension .png. By default, the image will be inverted, so that increasing flux is represented with darker pixels. Use the --noninverted flag for lighter pixels with increasing flux.
Pixel fluxes are exact integrals of an interpolated flux density across the image, with interpolations derived from flux densities calculated on a regular grid. Three interpolation schemes are supported:
- midpoint: grid points at pixel centers with flux assumed constant across each pixel.
- bilinear: grid points at pixel corners with flux assumed to be linear in both x and y across each pixel.
- bicubic: grid points at pixel corners with flux assumed to be cubic in both x and y across each pixel.
Use oversampling to calculate on a finer grid of sub-pixels that are combined into the output pixels. Use a margin to perform transforms on a larger image and avoid wrap-around artifacts due to the periodic nature of FFT. Note that a negative margin is also allowed and sometimes useful for rapidly generating images of compact objects in a large (mostly zero flux) image.
You can add a constant flux offset to all pixels (default zero), or set the total flux normalization (before any offset, default one). Use the printsum option to print the pixel flux sum (including any offset).
Two components can be optionally added to each pixel flux: a Gaussian component with the specified noiseRMS in the (arbitrary) output flux units, and a Poisson photon shot noise generated by converting signal flux to an expected number of photons using the specified gain (in arbitrary flux units per photon). By default, neither noise component is generated. Specify the random seed for reproducible noise.