Nearby Solving

In nearby solves we already have a good idea what the center coordinate of our image is, but still it may be off by several degrees or so. So the nearby solving will scan the nearby areas for possible matches, if a match is not immediately found from the provided center coordinates.

We assume that we have a fair idea of the image's field radius. The better the idea and the less we need to guess, the faster the solve process will be.

There are two ways to provide the parameters to the solver in nearby mode: manually or from FITS headers.

Manual parameters

When we do not have a FITS file, there are no FITS headers to dig the coordinates from and the solver needs manual input. Minimum parameters example:

watney-solve nearby --image andromeda.png --manual --ra "00 41 02" --dec "41 07 50" --field-radius 2 --search-radius 10

You may also just run watney-solve nearby to get the list of available parameters.

For reference, the parameters available in watney-solve at the time of writing are:

Parameter	Description
-m, --manual	Specifies that the center is provided using --ra and --dec parameters and scope radius in --field-radius.
-r, --ra	The search center in RA coordinate (either decimal or hours minutes seconds).
-d, --dec	The search center in Dec coordinate (either decimal or degrees minutes seconds).
-f, --field-radius	The (telescope) field radius (in degrees) to use. Mutually exclusive with the --field-radius-range parameter. Value should be between 0.1 .. 16.
-g, --field-radius-range	The (telescope) field radius (in degrees) to use as a min-max range. Separate the values with a dash, e.g. '4-2.5'. The order of those two values does not matter. If this argument is set, it will override --field-radius. Range should be set between 0.1 .. 16.
-n, --field-radius-steps	(Default: 0) How many intermediate steps to use between min-max when trying out field radii when --field-radius-range argument is given, otherwise this value will be ignored. If given the parameter 'auto', the number of intermediate steps will be auto-generated: the tried field radius value will be halved until minimum value is reached. If not given, defaults to 0.
-h, --use-fits-headers	Specifies that the assumed center and field radius is provided by the file FITS headers. Will result in an error if the input file is not FITS or it does not contain the required FITS headers.
-s, --search-radius	Required. The search radius (deg), the solver search will cover this area around the center coordinate.
-p, --use-parallelism	(Default: false) Use parallelism, search multiple areas simultaneously.
-i, --image	Required. The image file to solve.
--out-format	(Default: json) Output format. Valid values are 'json', 'tsv'.
-o, --out	Output file. If not set, output will be printed to stdout.
-w, --wcs	Output filename for WCS coordinates. If given, a FITS file containing WCS headers will be produced.
-x, --lower-density-offset	(Default: 1) Include this many lower quad density passes in search (compared to image quad density).
-z, --higher-density-offset	(Default: 1) Include this many higher quad density passes in search (compared to image quad density).
--max-stars	(Default: 0) Maximum number of stars to use from the image. When not given, the solver decides itself. When given, the solver uses this number. In cases of very high star count present in the image (wide-field images), the solve may fail if this number is not set high enough. A low number of stars will speed up the solve, since it means less calculations are required, but there's a bigger chance that the solve will fail. 300 is generally a good value.A high number (> 1000) will however also affect performance due to the high number of calculations, and this gets especially noticeable with blind solves.
--sampling	(Default: 0) Try to solve the field using a sampled set of database quads first. With sampling, we try to match the image's star quads to only a fraction of the available database quads at a time, effectively making the search faster. The idea is that even if we can't find a solution (enough matching quads), we still get potential matching areas with one or more matching quad, which we can then scan with a full set of database quads to get the answer faster. Less work is performed in scanning, which makes it faster. Recommended (and default) value to use is 4 but some images may well solve faster with higher values. Too high values will however result in time wasted in scanning and making the solve actually slower.
--extended	(Default: false) Produce extended output. This will print out a lot of additional detail about the solve.
--log-stdout	(Default: false) Verbose logging. If true, will log a lot of additional lines to stdout.
--log-file	Verbose logging. Give a filename to print verbose log lines into a file.
--use-config	Path to configuration file. By default tries to load watney-solve-config.yml in the same directory where the solver is.

Use FITS headers

When solving FITS files, we may use the --use-fits-headers to provide us the field radius and the assumed center coordinate. The program will read the headers and you will not need to supply --ra, --dec or --field-radius parameters. Example:

watney-solve nearby --image andromeda.fits --use-fits-headers --search-radius 10

The FITS reader will try to read coordinates from RA, DEC, RA_OBJ, DEC_OBJ, OBJCTRA, OBJCTDEC, and also determine the field size from PIXSIZEn, XBINNING, YBINNING and FOCALLEN. If those records are found, the header information can be used.

Note that you can still just as well use manual coordinates with FITS files.

Examples

Solve a field with known field radius and assumed known center point, searching with a radius of 20 degrees:

watney-solve nearby --image andromeda.fits --field-radius 2 --ra 10.72 --dec 41.25 --search-radius 20

Solve a field with uncertain field radius (trying 4 .. 1 degrees) and assumed known center point, using sampling, searching with a radius of 20 degrees:

watney-solve nearby --image andromeda.fits --field-radius-range 4-1 --sampling 8 --ra 10.72 --dec 41.25 --search-radius 20

The output

The standard output (non-extended) as JSON looks like:

{
  "success": true,
  "ra": 10.723095695998863,
  "dec": 41.25033946510212,
  "ra_hms": "0 42 53.54",
  "dec_dms": "41 15 1.32",
  "fieldRadius": 1.8673415850842443,
  "orientation": -61.81787691614857,
  "pixScale": 2.397351285596479,
  "parity": "flipped"
}

Where:

• success: true or false
• ra: the RA coordinate as decimal degrees
• dec: the Dec coordinate as decimal degrees
• ra_hms: the RA coordinate as Hours Minutes Seconds
• dec_dms: the Dec coordinate as Degrees Minutes Seconds
• fieldRadius: the field radius in degrees (imagine a circle drawn around the image's widest corners)
• orientation: the field orientation in degrees
• pixScale: pixel scale, in arc seconds per pixel
• parity: whether the image is flipped (mirrored, value "flipped") or not (value "normal")

The TSV output is plain key-value strings, with key and value separated by a tab character ('\t'):

success true
ra      10.723095695998865
dec     41.25033946510212
ra_hms  0 42 53.54
dec_dms 41 15 1.32
fieldRadius     1.8673415850842499
orientation     -61.81787691614857
pixScale        2.397351285596486
parity  flipped

The extended output (--extended flag) gives out some more information:

{
  "success": true,
  "ra": 10.723095695998865,
  "dec": 41.25033946510212,
  "ra_hms": "0 42 53.54",
  "dec_dms": "41 15 1.32",
  "fieldRadius": 1.8673415850842419,
  "orientation": -61.81787691614857,
  "pixScale": 2.397351285596476,
  "parity": "flipped",
  "starsDetected": 7482,
  "starsUsed": 300,
  "timeSpent": "00:00:00.4559659",
  "searchIterations": 2,
  "searchRunCenter": "[10.7, 41]",
  "searchRunRadius": 3.0,
  "quadMatches": 168,
  "fieldWidth": 2.9827045578296154,
  "fieldHeight": 2.247516830246696,
  "fits_cd1_1": 0.0003144047999479153,
  "fits_cd1_2": -0.0005871847097447616,
  "fits_cd2_1": 0.0005869984562423269,
  "fits_cd2_2": 0.0003146098369413153,
  "fits_cdelt1": 0.0006658960623559533,
  "fits_cdelt2": 0.0006661570632052782,
  "fits_crota1": -61.81787691614857,
  "fits_crota2": -61.825858880383215,
  "fits_crpix1": 2238.9011931383843,
  "fits_crpix2": 1686.9827798740419,
  "fits_crval1": 10.723067825946227,
  "fits_crval2": 41.25027604788231
}

• timeSpent: time spent on the solve
• searchIterations: how many areas were searched
• searchRunCenter: the center coordinate of the search run that produced the result
• searchRunRadius: the field radius that was used in the above search run
• quadMatches: how many star quads matched
• fieldWidth: the width of the field, in degrees
• fieldHeight: the height of the field, in degrees
• fits_cd1_1 .. fits_cd2_2: for FITS, rotation and scale matrix
• fits_cdelt1..2: for FITS, coordinate increment along axis n
• fits_crota1..2: for FITS, coordinate system rotation angle
• fits_crpix1..2: for FITS, pixel coordinates of the reference point to which the projection and the rotation refer
• fits_crval1..2: for FITS, the center coordinate as right ascension and declination or longitude and latitude in decimal degrees

Additionally, the WCS file (a FITS file with headers only) that contains the WCS headers can be saved using the --wcs <filename> parameter.

How it works

The technicality is described in more detail in NearbySearchStrategy.