hexgrid

Synopsis

Create a regular hexagonal grid and apply to input image

Syntax

hexgrid  infile outfile sideline [binimg] [xref] [yref] [verbose]
[clobber]

Description

hexgrid creates a uniform grid of hexagonal shaped regions. Hexagons are highest order polygon which can be used to uniformly tile a plane; thus they are are the closest approximation to a circular grid. All hexagons have the same size and orientation. Users can specify a center location which centers one of the hexagons; the rest of the field then is shifted to accommodate this constraint.

The output from hexgrid is a map file, where the pixel values indicate to which group each pixel belongs. If a binimg is supplied, hexgrid will apply the grouping to the infile and the result saved in the binimg file.

Examples

Example 1

% hexgrid img.fits hex.map sidelen=10

This example creates an output map file, hex.map, the same size and dimensions as the input file, img.fits. Each hexagon will have a side length=10 pixels (in image or logical pixel). Note: due to quantization, the side length may vary +/-1.

If the input image contains any pixel values that have a value of NaN, or are outside the image's data subspace, then those pixels will be left ungrouped (map values equal to zero).

The output image contains integer values, where pixels with the same value belong to the same hexagon. Note that the pixel values do not always start at one (1), nor are they guaranteed to be consecutive. A pixel value equal to zero (0) means that the pixel is ungrouped.

Example 2

% hexgrid img.fits hex.map sidelen=10 xref=512 yref=512

Same as the previous example; however, a reference location has been specified. The reference location is specified in logical (image) coordinates. When these parameters are set, the tool will adjust the starting location of the hexagonal grid such that the reference position is in the center of a hexagon.

Example 3

% hexgrid img.fits hex.map sidelen=10 binimg=hex.img

Same as first example, except with the binimg parameter specified, the script will apply the grouping scheme in the hex.map output file to the img.fits infile, and output the binned image, hex.img.

Parameters

name	type	ftype	def	min	max	reqd
infile	file	input				yes
outfile	file	output				yes
sideline	real		10	3		yes
binimg	file	output
xref	real		0
yref	real		0
verbose	integer		1	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input image.

Null and NaN pixels, as well as those pixels outside the image subspace will not be grouped.

Parameter=outfile (file required filetype=output)

Output map file

The outfile is a map file containing integer pixel values. The pixel values indicate which pixels are grouped together by the algorithm. A pixel value of 0 are pixels which are ungrouped (ie outside the image subspace).

Parameter=sideline (real required default=10 min=3)

The side length of each hexagon

The side length is expressed in logical (ie image) pixels. The true side lengths may vary by +/- 1 pixel due to quantization effect. Also due to quantization, the tool has lower limit of 3 image pixels; smaller than that and the hexagons become squares.

Parameter=binimg (file filetype=output)

Optional, output binned image

If the binimg file is specified, the script will use the input image and the output map file to create a binned version of the input image.

Parameter=xref (real default=0)

X coordinate of the reference location in image coordinates

The reference location is specified in logical (image) coordinates. When these parameters are set, the tool will adjust the starting location of the hexagonal grid such that the reference position is in the center of a hexagon. The exact group (map ID) where the reference location is located is undetermined.

Parameter=yref (real default=0)

Y coordinate of the reference location in image coordinates

Parameter=verbose (integer default=1 min=0 max=5)

Amount of chatter from the tool.

Parameter=clobber (boolean default=no)

Delete outfile if it already exists?

About Contributed Software

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.

Bugs

There are no known bugs for this tool.