Gwyscan Library

GWYSCANDLL_API GwyscanResult  gwyscan_generate_xyz_data (double *xypos, double *zdata, int n, double xreal, double yreal, double xoffset, double yoffset, int reserved) 
Fills preallocated 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 spacefilling 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 spacefilling 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 twodimensional 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...  
GWYSCANDLL_API int gwyscan_create_path_octave_2d  (  double *  xypos, 
int  order,  
int  noctaves,  
double  xreal,  
double  yreal,  
double  xoffset,  
double  yoffset  
) 
Creates twodimensional octave profile scan starting from the finest resolution.
The function creates a twodimensional 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 powerof2 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).
xypos  is an allocated array of xy positions to fill. Pass NULL to just calculate number of positions. 
order  is the base2 logarithm of the basic block size 
noctaves  is the number of scale multiplications by 2 
xreal  is a requested physical range of the scan in x direction, in meters. 
yreal  is a requested physical range of the scan in y direction, in meters. 
xoffset  is a requested offset of the scan in x direction, in meters. 
yoffset  is a requested offset of the scan in y direction, in meters. 
xypos
is NULL. 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 powerof2 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 XXXXXXXXXXXXX order=3, noctaves=2 XXXXXXXXXXXXXXXXX order=2, noctaves=3 XXXXXXXXXXX
Note that these examples always start with the finest block. However, the positions of the finerscale 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.
xypos  is an allocated array of xy positions to fill. Pass NULL to just calculate number of positions. 
order  is the base2 logarithm of the basic block size in a profile 
noctaves  is the number of scale multiplications by 2 in a profile 
nprofiles  is the number of horizontal profiles to construct 
xreal  is a requested physical range of the scan in x direction, in meters. 
yreal  is a requested physical range of the scan in y direction, in meters. 
xoffset  is a requested offset of the scan in x direction, in meters. 
yoffset  is a requested offset of the scan in y direction, in meters. 
xypos
is NULL. 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.
xypos  is an allocated array of xy positions to fill. Pass NULL to just calculate number of positions. 
n  is the number of points the path should have 
xreal  is a requested physical range of the scan in x direction, in meters. 
yreal  is a requested physical range of the scan in y direction, in meters. 
xoffset  is a requested offset of the scan in x direction, in meters. 
yoffset  is a requested offset of the scan in y direction, in meters. 
xypos
is NULL. 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 (onedirectional, bidirectional) 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.
xypos  is an allocated array of xy positions to fill. Pass NULL to just calculate number of positions. 
xres  is a requested x resolution of the scan. 
yres  is a requested y resolution of the scan 
xreal  is a requested physical range of the scan in x direction, in meters. 
yreal  is a requested physical range of the scan in y direction, in meters. 
xoffset  is a requested offset of the scan in x direction, in meters. 
yoffset  is a requested offset of the scan in y direction, in meters. 
angle  is a requested angle of scan. 
direction  is a requested scan method. 
xypos
is NULL. 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 spacefilling curve.
Function creates a scan path formed by an ordern
Hilbert spacefilling 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 topleft corner (point with smallest x and y) and ends in the topright 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.
xypos  is an allocated array of xy positions to fill. Pass NULL to just calculate number of positions. 
order  is the Hilbert curve order (a nonnegative number). 
xreal  is a requested physical range of the scan in x direction, in meters. 
yreal  is a requested physical range of the scan in y direction, in meters. 
xoffset  is a requested offset of the scan in x direction, in meters. 
yoffset  is a requested offset of the scan in y direction, in meters. 
xypos
is NULL. 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 spacefilling 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 spacefilling 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.
xypos  is an allocated array of xy positions to fill. Pass NULL to just calculate number of positions. 
order  is the Hilbert curve order at the finest resolution (a nonnegative number). 
coarse_order  is the Hilbert curve order for the initial coarse scan. 
skip_order  is the Hilbert curve order for points that should not be measured at all. 
xreal  is a requested physical range of the scan in x direction, in meters. 
yreal  is a requested physical range of the scan in y direction, in meters. 
xoffset  is a requested offset of the scan in x direction, in meters. 
yoffset  is a requested offset of the scan in y direction, in meters. 
xypos
is NULL. 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.
xypos  is an allocated array of xy positions to fill. Pass NULL to just calculate number of positions. 
n  is the number of points the spiral should have 
xreal  is a requested physical range of the scan in x direction, in meters. 
yreal  is a requested physical range of the scan in y direction, in meters. 
xoffset  is a requested offset of the scan in x direction, in meters. 
yoffset  is a requested offset of the scan in y direction, in meters. 
xypos
is NULL. 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.
xypos  is an allocated array of xy positions to fill. Pass NULL to just calculate number of positions. 
n  determines the smallest step within the profile 
nprofiles  is the number of horizontal profiles to construct 
xreal  is a requested physical range of the scan in x direction, in meters. 
yreal  is a requested physical range of the scan in y direction, in meters. 
xoffset  is a requested offset of the scan in x direction, in meters. 
yoffset  is a requested offset of the scan in y direction, in meters. 
xypos
is NULL. GWYSCANDLL_API GwyscanResult gwyscan_generate_xyz_data  (  double *  xypos, 
double *  zdata,  
int  n,  
double  xreal,  
double  yreal,  
double  xoffset,  
double  yoffset,  
int  reserved  
) 
Fills preallocated data with a virtual random scan in requested physical range.
Fills preallocated 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.
xypos  is the array of x, y position tuples, this array should have n*2 values 
zdata  is the array of z positions, this array should have n values 
n  is the number of nonequidistant data triplets available 
xreal  is physical dimension of the array to be filled. 
yreal  is physical dimension of the array to be filled. 
xoffset  is the filled data x offset (in real dimensions) 
yoffset  is the filled data y offset (in real dimensions) 
reserved  is reserved, should be 0 