.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
.TH GROPT "1" "January 2021" "gropt 0.9.4 (2021.01.24)" "User Commands"
.SH NAME
gropt \- performing ray tracing computation of optical systems
.SH SYNOPSIS
.B gropt
[\fI\,options\/\fR] \fI\,<input> \/\fR[...] [\fI\,-o <output>\/\fR]
.SH DESCRIPTION
The purpose of the task `gropt` is to perform various computations in the framework of geometrical optics. The main input of the task is a descriptor file quantifying the various optical elements (lenses, mirrors, aperture stops, etc. and the respective materials) as well as the alignment geometry of these pieces. The output of `gropt` includes well\-known products of optical analysis such as ray transfer matrices, analysis for multiple wavelengths, ray diagrams, 3D models for visualization, spot diagrams, models for spatially quantized point\-spread functions, plate solutions and vignetting. The underlying ray trace library (see ./src/optcalc.[ch]) is also included in the program `firandom` in order to generate both precise and accurate simulated images that can be acquired with the given optical setup.
.SH OPTIONS
.SS "General options:"
.TP
\fB\-h\fR, \fB\-\-help\fR
Give general summary about the command line options.
.TP
\fB\-\-long\-help\fR, \fB\-\-help\-long\fR
Gives a detailed list of command line options.
.TP
\fB\-\-wiki\-help\fR, \fB\-\-help\-wiki\fR, \fB\-\-mediawiki\-help\fR, \fB\-\-help\-mediawiki\fR
Gives a detailed list of command line options in Mediawiki format.
.TP
\fB\-\-version\fR, \fB\-\-version\-short\fR, \fB\-\-short\-version\fR
Give some version information about the program.
.TP
<input>, \fB\-i\fR <input>, \fB\-\-input\fR <input>
Name of the input file describing the optical system. Note that all of the length dimensions, including offsets, curvatures, curvature radii and higher order aspherical constants are needed to be defined in the units of millimeters. Reading from standard input can be forced using a single dash "\-" as input file name.
.SS "Testing and benchmarking:"
.TP
\fB\-\-speed\-test\fR <time/seconds>
In this mode, gropt runs a speed test to figure out the number of rays that can be traced during the given interval of time. Note that this speed depends on the optical system itself, so one should specify a valid input (see \fB\-i\fR, \fB\-\-input\fR).
.SS "Common options for the various analysis modes:"
.TP
\fB\-l\fR, \fB\-\-lambda\fR, \fB\-\-wavelength\fR <wavelength/microns>
The wavelength (in microns) of the ray set of the actual analysis.
.TP
\fB\-f\fR, \fB\-\-focus\fR <focal\-plane\-position>
The position of the focal plane. It overrides the "focal" keyword in the input optical system description (see \fB\-i\fR, \fB\-\-input\fR for more).
.TP
\fB\-x\fR, \fB\-\-scale\fR <pixel\-scale>
The pixel scale (i.e. the pixel size), also in millimeters.
.TP
\fB\-a\fR, \fB\-\-angle\fR <incident\-angle/radians>|<normal_x>,<normal_y>
The incident angle of the incoming parallel rays. If a single parameter is given, then it is going to be interpreted as an angle in radians. If two parameters are given after \fB\-a\fR or \fB\-\-angle\fR then these are treated as the x and y components of the ray normal vector. By conventions, a single paramater of "a" is equivalent to "0,sin(a)".
.SS "Spot diagram analysis:"
.TP
\fB\-s\fR, \fB\-\-spot\-aperture\fR <radius>[,<number\-of\-rings>[,<position>]]
The radius, the number of the rings and the offset of spot aperture. If omitted, the number of the rings is going to be one and the offset of the spot aperture is going to be zero. Note that the option \fB\-o\fR, \fB\-\-output\fR or \fB\-\-output\-spot\fR is needed to be specified in order to perform a spot diagram analysis.
.TP
\fB\-o\fR, \fB\-\-output\fR, \fB\-\-output\-spot\fR <spot\-diagram\-output>
The name of the file to which the spot diagram output is intended to be written. To write the output to the standard output, use a dash (\-) as a file name. To write the output to the file named as a dash, use \fB\-o\fR ./\- or something equivalent.
.SS "Ray transfer matrix analysis:"
.TP
\fB\-t\fR, \fB\-\-transfer\fR
Perform a ray transfer matrix analysis. The results (namely, the computed focal plane offset and the effective focal length) are written to the standard output.
.SS "Exporting geometry:"
.TP
\fB\-d\fR, \fB\-\-output\-scad\fR <openscad\-file>
Exports the geometry of the input optical setup to an OpenSCAD file. This 3D model of the setup can then be viewed by running `openscad` whose input is the output this process.
.TP
\fB\-e\fR, \fB\-\-output\-eps\fR <encapsulated\-postscript\-file>
Exports the geometry of the input optical setup to an encapsulated PostScript file. This PostScript image can be considered as a planar diagram of the lens system. If \fB\-s\fR or \fB\-\-spot\-aperture\fR is defined, then rays are also drawn according to the specifications following these command\-line switches.
.SS "Determination of point-spread function:"
.TP
\fB\-z\fR, \fB\-\-psf\-half\-size\fR <half\-size>
The half size of the output point\-spread function. If this parameter is, for example, 3, then the resolution of the output point\-spread function will be 7x7. In general, if the parameter is H, then the output point\-spread function will have a resolution of (2H+1)x(2H+1). Note that the pixel scale of this computed point\-spread function is defined by \fB\-x\fR or \fB\-\-scale\fR.
.SH "REPORTING BUGS"
Report bugs to <apal@szofi.net>, see also https://fitsh.net/.
.SH COPYRIGHT
Copyright \(co 1996, 2002, 2004\-2008, 2010\-2016, 2018\-2020; Pal, Andras <apal@szofi.net>