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...

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...

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...

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...

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...

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...

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...

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...

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...

int	gwyscan_create_path_lissajous (double xypos, int a, double d, double xreal, double yreal, double xoffset, double yoffset, double angle, int Ncp)
	Creates Lissajous profile scans. More...

int	gwyscan_create_path_cycloid (double *xypos, double d, double xreal, double yreal, double xoffset, double yoffset, double angle)
	Creates cycloid profile scans. More...

int	gwyscan_create_path_rosette (double xypos, int a, double d, double xreal, double yreal, double xoffset, double yoffset, double angle, int Ncp)

Detailed Description

Function Documentation

int gwyscan_create_path_cycloid	(	double *	xypos,
		double	d,
		double	xreal,
		double	yreal,
		double	xoffset,
		double	yoffset,
		double	angle
	)

Creates cycloid profile scans.

Parameters

xypos	is an allocated array of xy positions to fill. Pass `NULL` to just calculate number of positions.
d	is a resolution (the largest distance near the starting point located in the center of the pattern).
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 in radians.

Returns: number of set elements or number of elements to allocate if xypos is NULL.

Examples:: create_path_cycloid.c.

int gwyscan_create_path_lissajous	(	double *	xypos,
		int	a,
		double	d,
		double	xreal,
		double	yreal,
		double	xoffset,
		double	yoffset,
		double	angle,
		int *	Ncp
	)

Creates Lissajous profile scans.

Parameters

xypos	is an allocated array of xy positions to fill. Pass `NULL` to just calculate number of positions.
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 in radians.
d	is a resolution (the largest distance near the starting point located in the center of the pattern).
a	is a number of the times of all sampling points over all crossing points (when a=1, sampling points are just all the cross points; when a>1, there are (a-1) sampling points between every two adjacent cross points along the path).
Ncp	is a number of self-intersection cross points (not including boundary points).

Returns: number of set elements or number of elements to allocate if xypos is NULL.

Examples:: create_path_lissajous.c.

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

xypos	is an allocated array of xy positions to fill. Pass `NULL` to just calculate number of positions.
order	is the base-2 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.

Returns: number of set elements or number of elements to allocate if xypos is NULL.

Examples:: create_path_octave_2d.c.

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

xypos	is an allocated array of xy positions to fill. Pass `NULL` to just calculate number of positions.
order	is the base-2 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.

Returns: number of set elements or number of elements to allocate if xypos is NULL.

Examples:: create_path_octave_profiles.c.

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

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.

Returns: number of set elements or number of elements to allocate if xypos is NULL.

Examples:: create_path_random.c.

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

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 in radians.
direction	is 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, and modify_path_revert.c.

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

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 non-negative 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.

Returns: number of set elements or number of elements to allocate if xypos is NULL.

Examples:: create_path_space_filling.c.

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

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 non-negative 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.

Returns: number of set elements or number of elements to allocate if xypos is NULL.

Examples:: create_path_space_filling_progressive.c.

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

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.

Returns: number of set elements or number of elements to allocate if xypos is NULL.

Examples:: create_path_spiral.c.

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

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.

Returns: number of set elements or number of elements to allocate if xypos is NULL.

Examples:: create_path_wichmann_profiles.c.

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

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 non-equidistant 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

Returns: error code.