Read Me

Libgwyscan is a small MIT-licensed embeddable library that provides functions
for reading and writing of Gwyddion GWY files. It contains functions for both
the generic GWY file format and specific data structures actually used by
Gwyddion to represent scanning probe microscopy data.

Website: http://libgwyscan.sourceforge.net/
Author:  Petr Klapetek <klapetek@gwyddion.net>

See the examples in examples/.

-----------------------------------------------------------------------------

0. REQUIREMENTS

An ISO C compiler providing a few C99 features, in particular:
- the inline keyword
- stdbool.h
- stdint.h

Libgwyscan uses FLANN - Fast Library for Approximate Nearest Neighbors.
Website: http://www.cs.ubc.ca/research/flann/

Libgwyscan uses Libgwyfile internally for reading and writing Gwyddion GWY 
files. Website: http://libgwyfile.sourceforge.net/ 

-----------------------------------------------------------------------------

1. BUILDING AS A NORMAL (SHARED/STATIC) LIBRARY ON UNIX

This may be a good start even if you intend to embed the library to ensure it
works fine on your system.

Libgwyscan uses GNU autotools so run

    ./configure [--prefix=...]
    make
    make install

as usual to build it.

Documentation.  If you have doxygen you can run

    make doc

to HTML build API reference documentation in lib/doc/.  Read it on-line
otherwise.

-----------------------------------------------------------------------------

2. BUILDING AS A NORMAL LIBRARY WITH MSVC

MSVC 2015 project files are provided in subdirectory msvc2015.  The SLN file
is located in msvc2015/libgwyscan.  The files use relative paths to the
source and should work from the location where they distributed in the
archive.

-----------------------------------------------------------------------------

3. EMBEDDING THE LIBRARY

The entire library consists of four C files in lib:

    gwyscan.h (the header)
    gwyscan.c (the implementation)
    gwyfile.h
    gwyfile.c

Just copy them to your program.

See the top of gwyfile.c for preprocessor defines that you may want to adjust
to define the system configuration.  Most importantly, ensure the library is
built for the correct byte order (little/big endian).  Alternatively, you can
provide a config.h that defines the system configuration.

If your C compiler does not support C99 features such as the bool type or
inline keyword, see the top if gwyfile.c for some possible remedies.

-----------------------------------------------------------------------------

4. USAGE EXAMPLES

See the files in examples subdirectory:
- create_regular_scan_path_pixels (creates a simple scan path, based on regular 
matrix of points)
- save_gwyddion_arrays (saves multiple different arrays to a Gwyddion GWY file)
- save_gwyddion_similar_arrays (saves multiple arrays (channels) having the same
resolution and physical range to a Gwyddion GWY file)