libics v.1.6.6
Image Cytometry Standard file reading and writing.
This is the reference library for ICS (Image Cytometry Standard), an
open standard for writing images of any dimensionality and data type to
file, together with associated information regarding the recording
equipment or recorded subject.
ICS version 1.0 and 2.0
=============================
ICS stands for Image Cytometry Standard, and was first proposed in:
P. Dean, L. Mascio, D. Ow, D. Sudar, J. Mullikin, "Propsed
standard for image cytometry data files", Cytometry, n.11,
pp.561-569, 1990.
It writes 2 files, one is the header, with an '.ics' extension, and the
other is the actual image data (with an '.ids' extension.)
ICS version 2.0 extends this standard to allow for a more versatile
placement of the image data. It can now be placed either in the same
'.ics' file or inbedded in any other file, by specifying the file name
and the byte offset for the data.
The advantage of ICS over other open standards such as TIFF is that it
allows data of any type and dimensionality to be stored. A TIFF file
can contain a collection of 2D images; it's up to the user to determine
how these relate to each other. An ICS file can contain, for exmaple, a
5D image in which the 4th dimension is the light frequency and the 5th
time. Also, all of the information regarding the microscope settings
(or whatever instument was used to acquire the image) and the sample
preparation can be included in the file.
This library is distributed under the GNU LESSER GENERAL PUBLIC
LICENSE. See the file GNU_LICENSE for terms.
The libics library is currently maintained by Scientific Volume Imaging
(https://svi.nl). Please mail comments, bugs and feature requests to:
libics@svi.nl
Documentation
==============================
Online documentation can be found at: https://svi-opensource.github.io/libics
Installation Instructions
===============================
Obtain the source distribution from
https://github.com/svi-opensource/libics
It is recommended you also install zlib (http://www.zlib.org).
- Compilation under UNIX / Linux / Mac OS X / Cygwin
Run the following commands from the source directory:
./configure
make
make install
Read the INSTALL file for more information.
The library can be tested for problems using
make check
- Compilation under Windows with Borland C++
Edit the paths defined at the beginning of Makefile.bcc, then type
make -f Makefile.bcc
from a command prompt in the source directory. This will create a file
libics.lib in the same directory. To build a dynamic library (DLL), type
make -f Makefile.bcc dynamic
The dynamic library libics.dll has an import library named
libics.dll.lib. To make a debug version add '-DDEBUG' to these commands.
To disable zlib support, remove the definition of ZLIB_SUPPORT from the
file Makefile.bcc.
When compiling a program that uses the dynamic library, you need to
define the USE_ICSLIB_DLL pre-processor variable.
- Compilation under Windows with Microsoft Visual C++ 9
Edit the path to Zlib defined at the beginning of Makefile.vc9, then
type
nmake /f Makefile.vc9
from a command prompt in the source directory. This will create a
dynamic library libics.dll in the same directory, and an import library
libics.lib. Change the definitions of SHARED or DEBUG in the makefile to
create static and/or debug versions of the library. To disable zlib
support, remove the definition of ZLIB_SUPPORT from the makefile.
When compiling a program that uses the dynamic library, you need to
define the USE_ICSLIB_DLL pre-processor variable.
- Compilation under Windows with older versions of Microsoft Visual C++
Edit the paths defined at the beginning of Makefile.vc6, then type
nmake /f Makefile.vc6
from a command prompt in the source directory. This will create a file
libics.lib in the same directory. To build a dynamic library, type
nmake /f Makefile.vc6 dynamic
The dynamic library libics.dll has an import library named
libics.dll.lib. To make a debug version add '/D DEBUG' to these
commands. To disable zlib support, remove the definition of ZLIB_SUPPORT
from the file Makefile.vc.
- Compilation with CMake under UNIX / Linux / Mac OS X / Cygwin
Run the following commands from outside the source directory
cmake <path/to/libics/sources>
make
make install
The library can be tested for problems using
make test
CMake can be used with the following options:
cmake ... -DCMAKE_BUILD_TYPE=Debug # build a debug version
cmake ... -DLIBICS_USE_ZLIB=Off # do not use zlib
cmake ... -DBUILD_SHARED_LIBS=On # build a shared library
cmake ... -DLIBICS_INCLUDE_CPP=Off # do not include the C++ interface
CMake projects using libics as a subproject can do
add_subdirectory(<path/to/libics/sources>)
target_link_libraries(target PRIVATE libics)
The include directory for libics will be automatically set, and the zlib
library will be linked if necessary.
- Compilation with cmake on Windows:
Type on the command line
cmake CMakeLists.txt
or use cmake GUI. Next, open sln file in Visual Studio and build solution.
CREDITS
=============
As of 2016, this library is maintained by Scientific Volume Imaging:
Scientific Volume Imaging Holding B.V.
Laapersveld 63, 1213 VB Hilversum, The Netherlands
https://www.svi.nl
This library was originally written and maintained by
Cris Luengo
(previously at) Delft University of Technology, Delft, NL
With help from
Bert Gijsbers, Scientific Volume Imaging BV, Hilversum, NL
(Most changes for version 1.3)
Frank de Jong, Delft University of Technology, Delft, NL
(IcsViewer utility improvements)
Fons Laan, Hubrecht Laboratorium, Utrecht, NL
(SCIL_Image compatability, make files, bug fixes)
Glenn Pierce
(Idea of opening in "rw" mode and history iterator)
David Svoboda, Masaryk University, Brno, Czech Republic
(Windows make files)
Peter Verveer, Scientific Volume Imaging BV, Hilversum, NL
(autoconf/automake script)
Paul Barber, University of Oxford, Oxford, United Kingdom
(cmake support)
Most of the code herein hasn't changed since the previous version, by
Dr. Hans T.M. van der Voort
Scientific Volume Imaging Holding B.V.
Laapersveld 63, 1213 VB Hilversum, The Netherlands
https://www.svi.nl
Which ultimately is based upon stuff written by:
Damir Sudar, Geert van Kempen, Jan Jitze Krol,
Chiel Baarslag, Fons Laan and Hans van der Voort.
HISTORY
=============
version 1.6.6
- Remove unused variables, avoiding compiler warning.
- Reorder cases in libics_top.c to match enum order
- Prevent a NULL pointer dereference on ICS syntax error, instead return
an Ics error.
- Replace fseek by _fseeki64() on Windows (64-bit safe). Based on
a patch submitted by Patrick Steele at Bitplane.
- For reference, add #define lines for possible string values as
used by SVI Huygens.
version 1.6.5
- Fix typo that causes out-of-bounds read.
version 1.6.4
- Add support for the noiseGain sensor parameter.
- Updated documentation with a list of supported sensor parameters.
- Support for building shared library on Windows with MinGW (Contributed by
Andrew Sun).
version 1.6.3
- Add support for storing the parameters of multi-detector microscopes.
- Support for 64 bit integer images.
- C++ interface.
- Improved CMake support
- Various bug fixes.
version 1.6.2
- Various bug fixes.
version 1.6.1
- Various bug-fixes.
- Added SPIM parameters.
- Added scattering parameters.
- New functions that return ICS string properties without string copying.
- Enable the use of negative strides.
version 1.6.0
Added functionality:
- Read and write sensor states.
- Support for cmake (contributed by Paul Barber).
version 1.5.4
- Small patch for supporting older Visual Studio version.
version 1.5.3
Changes / improvements / fixes:
- Fixed documentation and made explicit the current default to version
2.0 files.
- Added a "links" page to the documentation.
- Fixed tests 1 and 2a, which didn't work for big-endian machines.
- IcsWriteIcs() no longer overwrites data in the ByteOrder array.
- Fixed a segmentation violation when trying to write an image with
more than 5 dimensions.
- Added STED and detector parameters
- Fixed a bug to read large compressed files.
- Moved distribution to to github
version 1.5.2
Added functionality:
- UNIX make files now also generate a shared object using libtool.
- Added a Makefile for MSVC9.
- Added code to read COMPRESS-compressed data (.ids.Z).
- Added a test suite for the library.
Changes / improvements / fixes:
- Fixed bug in IcsGetDataWithStrides() when stride[0]==1.
- Fixed buffer overflow in IcsInternAddHistory() when adding lots of
history strings (not an exploitable vulnerability).
- Fixed bug in "l" option to IcsOpen, it behaved in the oposite way
to that advertised (bug #2943839).
The documentation still carries the version number 1.5.
version 1.5.1
Added functionality:
- IcsGetDataWithStrides() makes it easy to read in an ICS file into
a non-contiguous memory block such as an ROI, or to have different
dimension ordering in memory.
Changes / improvements / fixes:
- Fixed buffer overflow when trying to read a binary file (not an
exploitable vulnerability).
- Fixed bug in IcsInternAddHistory() if key==NULL.
- Rewrote IcsStrCpy(), it no longer needs the full len chars in dest
if src is shorter than len.
- The MATLAB MEX-files in support/matlab have finally been updated
to work on 64-bit platforms.
The documentation still carries the version number 1.5.
version 1.5
Added functionality:
- IcsSetIdsBlock() in low-level interface does fseek() on image data.
- Added "rw" mode to IcsOpen(). It's now possible to change metadata
in an ICS file.
- Added functions to delete, replace and retrieve history lines.
Changes / improvements / fixes:
- When reading and writing the ICS header file, the locale is set to
"C". This can be avoided with the "l" flag in IcsOpen().
- Fixed printf type mismatch according to bug #1245419.
- Added a bunch of 'const' modifiers according to feature request
#1245471.
- Reorganized a few things on the website and added a menu bar.
- Windows makefile changes relating to zlib.
- The strcasecmp/stricmp is finally resolved neatly.
- Renamed libics_compress.c to libics_gzip.c to prepare for the
inclusion of 'compress' decompression.
- Separated all history code into new libics_history.c file.
- Renamed a few internal functions in libics_write.c for consistency.
- Stop writing 0.0 in exponential notation.
- FileMode replaces Reading in the ICS data structure.
- Default 5th dimension now is "probe" instead of "p".
- The history lines are stored in a more useful fashion in the
IcsHeader struct. The struct itself changed.
version 1.4.1
Added functionality:
- Replaced config files with autoconf scripts.
Changes / improvements / fixes:
- The MAXPATHLEN define is replaced by a custom ICS_MAXPATHLEN. This
improves portability.
- The strcasecmp/stricmp thing is moved to where it matters:
libics_util.c
- Fixed compile bug when not linking with zlib.
- Moved web stuff to SourceForge.net.
- Changed the presentation page of the website a bit.
The documentation still carries the version number 1.4.
version 1.4
Added functionality:
- IcsSetDataWithStrides() allows writing data that is not stored in
the default x-y-z order, as well as a ROI in a larger image.
- IcsOpen() now also has a mode "rf" which avoids adding the ".ics"
extension to the given file name.
Changes / improvements / fixes:
- IcsVersion(), IcsReadIcs() and IcsGetIcsName() have an extra
parameter that indicates whether to add the extension to the given
file name or not.
- IcsInit() is now declared as a void function.
- The ICS structure has a new element: DataStrides.
- The file libics_compress.non.ansi.c is no longer.
- ICS_MAXDIM now is 10, up from 5.
- Allowing for axes scaling to be <= 0.
- Bugfix: small values are also written in scientific notation.
- Creation of DLL added to Windows Makefiles.
version 1.3 (Most changes by Bert Gijsbers)
Added functionality:
- Added PinholeSpacing to sensor parameters.
- IcsExtensionFind() finds extensions including .ids.Z and .ids.gz.
- IcsGetSensor and IcsSetSensor functions to get and set the sensor
parameters.
- IcsGetErrorText() returns string representation of error.
Changes / improvements / fixes:
- IcsGetIcsName() and IcsGetIdsName() now preserve the case in the
extension.
- 'struct _ICS' is now defined besides the 'ICS' typedef.
- IcsPrintIcs() would loop forever with non-zero sensor channels.
- Some %d format strings were called with a long int argument.
- Dimension types are now always size_t instead of int.
- Big improvements in the IcsViewer utility (by Frank de Jong).
version 1.2.1
A few small bug fixes:
- 12 bytes got lost because a free() call was missing.
- Reading a compressed file in blocks caused a SGV if the last imel
was included in the block (because of the CRC).
- support/icsviewer now adds some padding to each image line so that
Windows correctly displays the image.
The documentation still carries the version number 1.2.
version 1.2
Added functions:
- IcsGetROIData(), and the more general IcsGetDataBlock(),
IcsSkipDataBlock(). These funcions make it possible to read in
only a portion of the image data.
- IcsGetPreviewData() reads in a 2D sub-image, and converts it to
unsinged 8-bit integers for display.
- IcsLoadPreview() does the same, but just takes a file name. It
allocates the image buffer for you.
Changes / improvements / fixes:
- Many "unsigned int" parameters have been changed to "size_t". This
improves portability to 64-bit systems (and fixes some bugs too).
- Added return error codes to the documentation, as well as some
other interesting information.
- Corrected some bugs in the documentation.
- Added 'extern "C" {}' to the public header files so libics can be
used with C++.
version 1.1
Some improvements:
- Added support for the 'SCIL_TYPE' parameter (thanks to Fons Laan).
Call IcsSetScilType() or IcsGuessScilType() to write the parameter
to the ICS file.
- Any character is now allowed as a line separator, as specified in
the standard.
- ICS files with CR/LF pairs instead of CR characters only are now
also supported. The CR/LF pair problem is caused by some windows
applications that automatically convert 'text' files to the MS-DOS
format. These were not read by libics.
- Some low-level library functions have been renamed to make the
interface more consistent:
IcsRead() -> IcsReadIcs()
IcsWrite() -> IcsWriteIcs()
IdsRead() -> IcsReadIds()
IdsWrite() -> IcsWriteIds()
- The documentation has been updated and corrected.
version 1.0
Initial release.