Gwyscan Library
 All Files Functions Enumerations Enumerator Modules
Create Scan Path
GWYSCANDLL_API GwyscanResult gwyscan_generate_xyz_data (double *xypos, double *zdata, int n, double xreal, double yreal, double xoffset, double yoffset, int reserved)
 Fills pre-allocated data with a virtual random scan in requested physical range. More...
 
GWYSCANDLL_API int gwyscan_create_path_regular (double *xypos, int xres, int yres, double xreal, double yreal, double xoffset, double yoffset, double angle, GwyscanDirection direction)
 Creates scan path for regular (equidistant) measurements. More...
 
GWYSCANDLL_API int gwyscan_create_path_space_filling (double *xypos, int order, double xreal, double yreal, double xoffset, double yoffset)
 Creates scan path for equidistant measurement on a space-filling curve. More...
 
GWYSCANDLL_API int gwyscan_create_path_space_filling_progressive (double *xypos, int order, int coarse_order, int skip_order, double xreal, double yreal, double xoffset, double yoffset)
 Creates scan path for equidistant measurement on a space-filling curve on progressive resolutions. More...
 
GWYSCANDLL_API int gwyscan_create_path_spiral (double *xypos, int n, double xreal, double yreal, double xoffset, double yoffset)
 Creates spiral scan path incscribed to a rectangle on progressive resolutions. More...
 
GWYSCANDLL_API int gwyscan_create_path_random (double *xypos, int n, double xreal, double yreal, double xoffset, double yoffset)
 Creates completely random path incscribed to a rectangle. More...
 
GWYSCANDLL_API int gwyscan_create_path_octave_profiles (double *xypos, int order, int noctaves, int nprofiles, double xreal, double yreal, double xoffset, double yoffset)
 Creates randomized octave profile scans on progressive resolutions. More...
 
GWYSCANDLL_API int gwyscan_create_path_octave_2d (double *xypos, int order, int noctaves, double xreal, double yreal, double xoffset, double yoffset)
 Creates two-dimensional octave profile scan starting from the finest resolution. More...
 
GWYSCANDLL_API int gwyscan_create_path_wichmann_profiles (double *xypos, int n, int nprofiles, double xreal, double yreal, double xoffset, double yoffset)
 Creates Wichmann profile scans on progressive resolutions. More...
 

Detailed Description

Function Documentation

GWYSCANDLL_API int gwyscan_create_path_octave_2d ( double *  xypos,
int  order,
int  noctaves,
double  xreal,
double  yreal,
double  xoffset,
double  yoffset 
)

Creates two-dimensional octave profile scan starting from the finest resolution.

The function creates a two-dimensional octave scan with the finest uniformly spaced block in the center, surrounded by increasingly coarse positions. Each coarses spacing is double of the previous finer one. The path forms a spiral, improving isotropy and minimizing the time needed to traverse the entire path. You can use this function also to generate a plain square spiral path without any coarsening/refinement.

Parameter order determines the size of the basic block. At each power-of-2 scale, the position set contains a continuous block of (2^order)+1 times (2^order+1) equidistant positions (as a subset; there may be more positions between them). The minimum order is 2, corresponding to a 5x5 basic block.

Parameter noctaves determines how many times the refinement (or coarsening if you view it from the other side) progresses. If you pass 0 the scan path will consist only of a simple block of equidistant positions.

If you pass NULL for xypos the function then just calculates and returns the number of positions in the path (n). This is the recommended way of finding out how large xypos array you need to create. Note that each position has two coordinates so you must allocate xypos as array with 2*n elements.

The smallest horizontal step is equal to xreal/2^(order + noctaves) and the smallest vertical step is equal to yreal/2^(order + noctaves).

Parameters
xyposis an allocated array of xy positions to fill. Pass NULL to just calculate number of positions.
orderis the base-2 logarithm of the basic block size
noctavesis the number of scale multiplications by 2
xrealis a requested physical range of the scan in x direction, in meters.
yrealis a requested physical range of the scan in y direction, in meters.
xoffsetis a requested offset of the scan in x direction, in meters.
yoffsetis a requested offset of the scan in y direction, in meters.
Returns
number of set elements or number of elements to allocate if xypos is NULL.
Examples:
create_path_octave_2d.c.
GWYSCANDLL_API int gwyscan_create_path_octave_profiles ( double *  xypos,
int  order,
int  noctaves,
int  nprofiles,
double  xreal,
double  yreal,
double  xoffset,
double  yoffset 
)

Creates randomized octave profile scans on progressive resolutions.

The function creates a set of horizontal profiles, each consisting of a randomised octave scan. A randomised octave profile contains, as subsets, uniform sequences of positions at spaced at different powers of 2 of some base step.

Parameter nprofiles determines the number of profiles. Each profile is scanned continuously but the ordering of individual profiles provides progressive refinement of the image. In particular, the uppermost profile is scanned first, then the lowermost profile, then the middle profile, etc. recursively.

Parameter order determines the size of the basic block. At each power-of-2 scale, it is guaranteed that each profile contains a continuous block of (2^order)+1 equidistant positions (as a subset; there may be more positions between them).

Parameter noctaves determines how many times the refinement (or coarsening if you view it from the other side) progresses. If you pass 0 each profile will consist only of a simple block of equidistant positions.

Some examples (X denotes measurement position, - denotes movement):

order=3, noctaves=0
XXXXXXXXX

order=3, noctaves=1
XXXXXXXXX-X-X-X-X

order=3, noctaves=2
XXXXXXXXX-X-X-X-X---X---X---X---X

order=2, noctaves=3
XXXXX-X-X---X---X-------X-------X

Note that these examples always start with the finest block. However, the positions of the finer-scale blocks within the entire profile are randomised and the refinement can occur anywhere inside the profile.

The smallest horizontal step is equal to xreal/2^(order + noctaves).

If you pass NULL for xypos the function then just calculates and returns the number of positions in the path (n). This is the recommended way of finding out how large xypos array you need to create. Note that each position has two coordinates so you must allocate xypos as array with 2*n elements.

Parameters
xyposis an allocated array of xy positions to fill. Pass NULL to just calculate number of positions.
orderis the base-2 logarithm of the basic block size in a profile
noctavesis the number of scale multiplications by 2 in a profile
nprofilesis the number of horizontal profiles to construct
xrealis a requested physical range of the scan in x direction, in meters.
yrealis a requested physical range of the scan in y direction, in meters.
xoffsetis a requested offset of the scan in x direction, in meters.
yoffsetis a requested offset of the scan in y direction, in meters.
Returns
number of set elements or number of elements to allocate if xypos is NULL.
Examples:
create_path_octave_profiles.c.
GWYSCANDLL_API int gwyscan_create_path_random ( double *  xypos,
int  n,
double  xreal,
double  yreal,
double  xoffset,
double  yoffset 
)

Creates completely random path incscribed to a rectangle.

The function creates...

If you pass NULL for xypos the function then just calculates and returns the number of positions in the path (n). This is the recommended way of finding out how large xypos array you need to create. Note that each position has two coordinates so you must allocate xypos as array with 2*n elements.

Parameters
xyposis an allocated array of xy positions to fill. Pass NULL to just calculate number of positions.
nis the number of points the path should have
xrealis a requested physical range of the scan in x direction, in meters.
yrealis a requested physical range of the scan in y direction, in meters.
xoffsetis a requested offset of the scan in x direction, in meters.
yoffsetis a requested offset of the scan in y direction, in meters.
Returns
number of set elements or number of elements to allocate if xypos is NULL.
Examples:
create_path_random.c.
GWYSCANDLL_API int gwyscan_create_path_regular ( double *  xypos,
int  xres,
int  yres,
double  xreal,
double  yreal,
double  xoffset,
double  yoffset,
double  angle,
GwyscanDirection  direction 
)

Creates scan path for regular (equidistant) measurements.

Function creates an equidistant scan path consisting of a certain number of equally spaced points in a matrix (eventually rotated matrix). Different regimes of scanning (one-directional, bi-directional) are supported.

The organisation of individual pixels is always the same, so the results can be directly used for e.g. a bitmap. The following data organisation is used (assuming that you have requested 4x4 resolution measurement)

mode GWYSCAN_DIRECTION_FORWARD: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

function returns 16

mode GWYSCAN_DIRECTION_REVERSE: 3 2 1 0 7 6 5 4 11 10 9 8 14 14 13 12

function returns 16

mode GWYSCAN_DIRECTION_BIDIRECTIONAL: 0 1 2 3 7 6 5 4 8 9 10 11 15 14 13 12

function returns 16

in mode GWYSCAN_DIRECTION_BOTH, two arrays are taken - at each line both forward and reverse data are collected:

0 1 2 3 7 6 5 4

8 9 10 11 15 14 13 12

16 17 18 19 23 22 21 20

24 25 26 27 31 30 29 28

function returns 32

mode GWYSCAN_DIRECTION_FORWARD_REFINE 0 1 2 3 12 13 14 15 8 9 10 11 4 5 6 7

line order for 10 lines: 0 9 4 2 6 7 5 3 1 8

mode GWYSCAN_DIRECTION_FORWARD_ALTERNATEBLOCK = 5 line order: 0 1 2 3 8 9 10 11 4 5 6 7 12 13 14 15

line order for 10 lines: 0 2 4 6 8 1 3 5 7 9

If you pass NULL for xypos the function then just calculates and returns the number of positions in the path (n). This is the recommended way of finding out how large xypos array you need to create. Note that each position has two coordinates so you must allocate xypos as array with 2*n elements.

Parameters
xyposis an allocated array of xy positions to fill. Pass NULL to just calculate number of positions.
xresis a requested x resolution of the scan.
yresis a requested y resolution of the scan
xrealis a requested physical range of the scan in x direction, in meters.
yrealis a requested physical range of the scan in y direction, in meters.
xoffsetis a requested offset of the scan in x direction, in meters.
yoffsetis a requested offset of the scan in y direction, in meters.
angleis a requested angle of scan.
directionis a requested scan method.
Returns
number of set elements or number of elements to allocate if xypos is NULL.
Examples:
create_path_regular.c, modify_path_flip_horizontal.c, modify_path_flip_vertical.c, modify_path_insert.c, modify_path_revert.c, and preview.c.
GWYSCANDLL_API int gwyscan_create_path_space_filling ( double *  xypos,
int  order,
double  xreal,
double  yreal,
double  xoffset,
double  yoffset 
)

Creates scan path for equidistant measurement on a space-filling curve.

Function creates a scan path formed by an order-n Hilbert space-filling curve. The positions lie in a regular grid with 2^points along each axis. However, unlike in usual regular sampling, there is no distinction between fast and slow axis. The sampling pattern in both directions is very similar.

The path starts in the top-left corner (point with smallest x and y) and ends in the top-right corner (point with largest x and smallest y).

If you pass NULL for xypos the function then just calculates and returns the number of positions in the path (n). This is the recommended way of finding out how large xypos array you need to create. Note that each position has two coordinates so you must allocate xypos as array with 2*n elements.

Parameters
xyposis an allocated array of xy positions to fill. Pass NULL to just calculate number of positions.
orderis the Hilbert curve order (a non-negative number).
xrealis a requested physical range of the scan in x direction, in meters.
yrealis a requested physical range of the scan in y direction, in meters.
xoffsetis a requested offset of the scan in x direction, in meters.
yoffsetis a requested offset of the scan in y direction, in meters.
Returns
number of set elements or number of elements to allocate if xypos is NULL.
Examples:
create_path_space_filling.c.
GWYSCANDLL_API int gwyscan_create_path_space_filling_progressive ( double *  xypos,
int  order,
int  coarse_order,
int  skip_order,
double  xreal,
double  yreal,
double  xoffset,
double  yoffset 
)

Creates scan path for equidistant measurement on a space-filling curve on progressive resolutions.

The Hilbert space filling curve is specified in documentation of gwyscan_create_path_space_filling().

Both gwyscan_create_path_space_filling() and this function construct equivalent sets of positions. This more complex function permits progressive refinement while keeping the basic properties of the space-filling curve approach.

The finest grid is given by order in the same manner as in gwyscan_create_path_space_filling().

Parameter coarse_order defines the coarse resolution at which the scanning should start. The path fills the grid at this resolution completely first with the Hilbert curve, then starts adding more positions by progressive refinement. Pass 0 to start from the single point curve and always progress by refinement. Pass the same value as order to avoid progressive refinement and scan immediately at the finest grid (as gwyscan_create_path_space_filling() does). The value of coarse_order should be always at most equal to order because you cannot start scanning at finer grid than you end at.

Furthermore, it can be specified that you have already measured positions up to order skip_order and do not want to measure these positions again. Pass -1 if you want to measure all positions. Generally, skip_order should be smaller than coarse_order because it makes no sense to specify that you want to measure some points and simultaneously that they should be skipped. If you do so skip_order takes precedence (and in the extreme case this function can even construct a completely empty path).

If you pass NULL for xypos the function then just calculates and returns the number of positions in the path (n). This is the recommended way of finding out how large xypos array you need to create. Note that each position has two coordinates so you must allocate xypos as array with 2*n elements.

Parameters
xyposis an allocated array of xy positions to fill. Pass NULL to just calculate number of positions.
orderis the Hilbert curve order at the finest resolution (a non-negative number).
coarse_orderis the Hilbert curve order for the initial coarse scan.
skip_orderis the Hilbert curve order for points that should not be measured at all.
xrealis a requested physical range of the scan in x direction, in meters.
yrealis a requested physical range of the scan in y direction, in meters.
xoffsetis a requested offset of the scan in x direction, in meters.
yoffsetis a requested offset of the scan in y direction, in meters.
Returns
number of set elements or number of elements to allocate if xypos is NULL.
Examples:
create_path_space_filling_progressive.c.
GWYSCANDLL_API int gwyscan_create_path_spiral ( double *  xypos,
int  n,
double  xreal,
double  yreal,
double  xoffset,
double  yoffset 
)

Creates spiral scan path incscribed to a rectangle on progressive resolutions.

The function creates Archimede's spiral path. The spriral is sampled uniformly with a step that is chosen automatically to obtain approximately equal resolutions in the radial and tangential directions. The path always has exactly the requested number of points and it is inscribed to the rectangle, which should be preferrably a square.

If you pass NULL for xypos the function then just calculates and returns the number of positions in the path (n). This is the recommended way of finding out how large xypos array you need to create. Note that each position has two coordinates so you must allocate xypos as array with 2*n elements.

Parameters
xyposis an allocated array of xy positions to fill. Pass NULL to just calculate number of positions.
nis the number of points the spiral should have
xrealis a requested physical range of the scan in x direction, in meters.
yrealis a requested physical range of the scan in y direction, in meters.
xoffsetis a requested offset of the scan in x direction, in meters.
yoffsetis a requested offset of the scan in y direction, in meters.
Returns
number of set elements or number of elements to allocate if xypos is NULL.
Examples:
create_path_spiral.c.
GWYSCANDLL_API int gwyscan_create_path_wichmann_profiles ( double *  xypos,
int  n,
int  nprofiles,
double  xreal,
double  yreal,
double  xoffset,
double  yoffset 
)

Creates Wichmann profile scans on progressive resolutions.

The function creates a set of profiles formed by Wichmann sparse rulers. Any distance between 1 and the ruler length (measured in multiples of the smallest step) is present in the ruler at least once as the distance between two positions.

Parameter nprofiles determines the number of profiles. Each profile is scanned continuously but the ordering of individual profiles provides progressive refinement of the image. In particular, the uppermost profile is scanned first, then the lowermost profile, then the middle profile, etc. recursively.

Parameter n determines the approximate smallest step in the profile, i.e. the ratio between xreal and the distance of two closest point on the profile. The total number of points on the path grows with square root of this parameter. The function automatically determines the Wichmann ruler parameters r and s to minimise the number of positions for given ruler length, but it does not guarantee the smallest step will be exactly as requested.

If you pass NULL for xypos the function then just calculates and returns the number of positions in the path (n). This is the recommended way of finding out how large xypos array you need to create. Note that each position has two coordinates so you must allocate xypos as array with 2*n elements.

Parameters
xyposis an allocated array of xy positions to fill. Pass NULL to just calculate number of positions.
ndetermines the smallest step within the profile
nprofilesis the number of horizontal profiles to construct
xrealis a requested physical range of the scan in x direction, in meters.
yrealis a requested physical range of the scan in y direction, in meters.
xoffsetis a requested offset of the scan in x direction, in meters.
yoffsetis a requested offset of the scan in y direction, in meters.
Returns
number of set elements or number of elements to allocate if xypos is NULL.
Examples:
create_path_wichmann_profiles.c.
GWYSCANDLL_API GwyscanResult gwyscan_generate_xyz_data ( double *  xypos,
double *  zdata,
int  n,
double  xreal,
double  yreal,
double  xoffset,
double  yoffset,
int  reserved 
)

Fills pre-allocated data with a virtual random scan in requested physical range.

Fills pre-allocated data with a virtual random scan in requested physical range. Generated data can be written to offset specified in physical range.

Note to obtain reasonable lateral dimensions xreal yreal xoffset yoffset should be around 1.0.

Parameters
xyposis the array of x, y position tuples, this array should have n*2 values
zdatais the array of z positions, this array should have n values
nis the number of non-equidistant data triplets available
xrealis physical dimension of the array to be filled.
yrealis physical dimension of the array to be filled.
xoffsetis the filled data x offset (in real dimensions)
yoffsetis the filled data y offset (in real dimensions)
reservedis reserved, should be 0
Returns
error code.