Locked History Actions

DeepZot/Imengine/CommandLine

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.

Model Specification

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.

Output Options

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.

Interpolation Scheme

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.

Sampling Options

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.

Flux Transformations

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).

Noise Model

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.