Commit 6cba94a0 authored by Stephane Glondu's avatar Stephane Glondu

Imported Upstream version 4.1.1

parent 11b9c3df
repo: e37886d73a98029822983bee73a2d90ceb4b298b
node: 668faa3494feaff8e7d79af79e9e393290e98107
branch: 4.1.0
node: e4e7c50d80c2160f914a129758023bbdd75d86d3
branch: 4.1.1
latesttag: v4.0.1
latesttagdistance: 56
latesttagdistance: 83
4.1.1
* omake --config clean up
* pkg-config is now used if exists in order to seek external libraries
4.1.0
* bmp was not linked with examples. Since bmp is pure ML libarary,
you may need to add -linkall to linker command to your build script,
......
=========================================================
CamlImages - Objective Caml image processing library
=========================================================
This library is reliable but still under development.
Requirements
=================
*** Requirements
To install CamlImages library, you need the following softwares:
To install CamlImages library, you need the following softwares:
* OCaml 4.00.1 or higher
(OCaml 3.11 and above might work with small trivial fixes,
but never tested)
* Findlib (aka ocamlfind,
http://www.camlcity.org/archive/programming/findlib.html)
* OMake (http://omake.metaprl.org/index.html)
* OCaml 4.00.1 or higher (OCaml 3.11 and above might work with small trivial fixes, but never tested)
* Findlib (aka ocamlfind, http://www.camlcity.org/archive/programming/findlib.html )
* OMake ( http://omake.metaprl.org/index.html )
Note that this is the minimum requirement: you can read/write BMP or
PXM (PPM, PGM, PBM) image formats but no other formats. If you want to
deal with other image formats, you need to install the corresponding
external libraries:
* libpng for PNG format
http://www.libpng.org/pub/png/libpng.html
http://sourceforge.net/projects/libpng/
* libjpeg for JPEG format
The Independent JPEG Group's software
ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz
* libexif for EXIF tags in JPEG files
* libtiff for TIFF format
http://www.libtiff.org/
ftp://ftp.remotesensing.org/pub/libtiff/
* libxpm for XPM format (could be already by the X server installation)
X contrib libraries ftp directory
ftp://ftp.x.org/contrib/libraries
* freetype for drawing texts using truetype fonts
The FREETYPE Project
http://sourceforge.net/projects/freetype/
* libpng for PNG format
* libjpeg for JPEG format
* libexif for EXIF tags in JPEG files
* libtiff for TIFF format
* libxpm for XPM format (could be already by the X server installation)
* freetype for drawing texts using truetype fonts
* libungif/libgif for GIF format
* ghostscript for PS format
* lablgtk2, an OCaml interface to gtk+
* libungif for GIF format
Libungif, a library for using GIFs
http://sourceforge.net/projects/libungif/
Installation
=====================================
* ghostscript for PS format
See http://www.ghostscript.com/
::
* lablgtk2, an Objective Caml interface to gtk+
http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/lablgtk.html
*** Installation procedure by omake
% yes no | omake --install
% omake --configure <configuration options>
% omake install
% yes no | omake --install
% omake --configure <configuration options>
% omake install
At omake --configure, you can specify CFLAGS and LDFLAGS
to add extra header and library search paths respectively. For example,
to add extra header and library search paths respectively. For example,::
% omake --configure CFLAGS="-I /usr/include/libexif" LDFLAGS="-L/opt/blah"
List of configurable variables
---------------------------------
CFLASG, INCLUDES, LDFLAGS: as usual.
CFLASG, INCLUDES, LDFLAGS: as usual.
ARG_WANT_<feature>=bool
ARG_WANT_<feature>=bool
Without specifying ARG_WANT_<feature>, omake --configure automatically
searches the availability of <feature> and enables it when found.
......@@ -77,21 +58,28 @@ List of configurable variables
Currently the following features are available:
GIF, PNG, JPEG, EXIF, TIFF, XPM, GS, LABLGTK2, GRAPHICS, FREETYPE
ARG_FREETYPE_CONFIG=string
ARG_PATH_GS=string
PATH of freetype-config and gs.
ARG_PATH_PKG_CONFIG=string
ARG_PATH_FREETYPE_CONFIG=string
ARG_PATH_GS=string
PATH of external commands like pkg-config, freetype-config and gs
Without specifying, omake tries to find them in the PATH.
Test
----
Before you actually install the library, you can check that it
Before you actually install the library, you can check that it
really works, by running examples in the test directory. For the test
programs,
programs,::
% cd test
% make
% omake
% ./test
% ./test.run
(./test.run is the bytecode executable and ./test the binary
executable).
Where to report building issues?
==========================================================
https://bitbucket.org/camlspotter/camlimages/issues?status=new&status=open
......@@ -23,7 +23,7 @@ PATH_RGB_TXT[]=
########################################################################
VERSION=4.1.0
VERSION=4.1.1
# for src/META
PACKAGE_NAME=camlimages
......@@ -33,53 +33,61 @@ OCAMLMKLIB=ocamlmklib
##################################################### Auto configuration
with_default(def, varname) =
if $(not $(defined $(varname)))
return $(def)
else
getvar($(varname))
true_if_not_defined(var)=
with_default(true, $(var))
failwith_if_defined(var, msg) =
if $(defined $(var)):
eprintln(Error: $(msg))
exit 1
get_have(varname) =
with_default(false, this.HAVE_$(varname)) # this required
get_support(varname) =
with_default(false, this.SUPPORT_$(varname)) # this required
# CFLAGS_xxx and LDFLAGS_xxx must exist
get_flags(varname) =
cflags = $(getvar this.CFLAGS_$(varname))
ldflags = $(getvar this.LDFLAGS_$(varname))
value $(string $(cflags) $(ldflags))
print_configured() =
println(--- Configuring)
println(wordsize $(WORD_SIZE))
println(--- C libraries)
println(libgif: $(HAVE_GIF))
println(libpng: $(HAVE_PNG))
println(libjpeg: $(HAVE_JPEG))
println(libexif: $(HAVE_EXIF))
println(libtiff: $(HAVE_TIFF))
println(libxpm: $(HAVE_XPM))
println(libz: $(HAVE_Z))
println(libgif: $(get_have GIF))
println(libpng: $(get_have PNG))
println(libjpeg: $(get_have JPEG))
println(libexif: $(get_have EXIF))
println(libtiff: $(get_have TIFF))
println(libxpm: $(get_have XPM))
println(libz: $(get_have Z))
println(--- Subpackages)
println(gif: $(SUPPORT_GIF) \($(string $(LDFLAGS_gif)\)))
println(png: $(SUPPORT_PNG) \($(string $(LDFLAGS_png)\)))
println(jpeg: $(SUPPORT_JPEG) \($(string $(LDFLAGS_jpeg)\)))
println(exif: $(SUPPORT_EXIF) \($(string $(LDFLAGS_exif)\)))
println(tiff: $(SUPPORT_TIFF) \($(string $(LDFLAGS_tiff)\)))
println(xpm: $(SUPPORT_XPM) \($(string $(LDFLAGS_xpm)\)))
println(freetype: $(SUPPORT_FREETYPE) \($(PATH_FREETYPE_CONFIG)\) \($(string $(LDFLAGS_freetype))\))
println(ps: $(SUPPORT_PS) \($(PATH_GS)\))
println(rgb.txt: $(SUPPORT_RGB_TXT) \($(string $(PATH_RGB_TXT))\))
println(lablgtk2: $(SUPPORT_LABLGTK2))
println(graphics: $(SUPPORT_GRAPHICS))
println(gif: $(get_support GIF) \($(get_flags gif)\))
println(png: $(get_support PNG) \($(get_flags png)\))
println(jpeg: $(get_support JPEG) \($(get_flags jpeg)\))
println(exif: $(get_support EXIF) \($(get_flags exif)\))
println(tiff: $(get_support TIFF) \($(get_flags tiff)\))
println(xpm: $(get_support XPM) \($(get_flags xpm)\))
println(freetype: $(get_support FREETYPE) \($(PATH_FREETYPE_CONFIG)\) \($(get_flags freetype)\))
println(ps: $(get_support PS) \($(PATH_GS)\))
println(rgb.txt: $(get_support RGB_TXT) \($(string $(PATH_RGB_TXT))\))
println(lablgtk2: $(get_support LABLGTK2))
println(graphics: $(get_support GRAPHICS))
println(--- Summary)
println(supported subpackages: $(string $(SUPPORTED_SUBPACKAGES)))
println(supported formats: $(string $(SUPPORTED_FORMATS)))
println(supported non-formats: $(string $(SUPPORTED_NON_FORMATS)))
println(--- Global compilation switch)
# CFLAGS and LDFLAGS are already defined when print_configured()
# is defined, so using CFLAGS here just prints the value of
# when this function is defined.
# CR jfuruse: Something messy which I do not understand yet happens here!
println(CFLAGS: $(string $(CAMLIMAGES_CFLAGS)))
println(LDFLAGS: $(string $(CAMLIMAGES_LDFLAGS)))
println(---)
true_if_not_defined(var)=
if $(not $(defined $(var)))
true
else
value $(getvar $(var))
failwith_if_defined(var, msg) =
if $(defined $(var)):
eprintln(Error: $(msg))
exit 1
.STATIC:
# Variables must be initialized inside .STATIC, if they should be
# exported out.
......@@ -100,9 +108,6 @@ failwith_if_defined(var, msg) =
setvar(public.NATIVE_ENABLED, 1)
export
# It seems changing CFLAGS and INCLUDES in .STATIC is not a good idea.
CAMLIMAGES_CFLAGS = $(CFLAGS) $(addprefix -I , $(INCLUDES))
WORD_SIZE = $(Word_size)
# Image formats implemented using external libraries or binaries
......@@ -120,108 +125,155 @@ failwith_if_defined(var, msg) =
# OCaml packages found likable
OCAMLPACKS[]=
# pkg-config
if $(true_if_not_defined ARG_WANT_PKG_CONFIG)
if $(defined ARG_PATH_PKG_CONFIG):
PATH_PKG_CONFIG = $(ARG_PATH_PKG_CONFIG)
export
else
PATH_PKG_CONFIG = $(Check_prog_in_path pkg-config)
export
export
# Zlib
HAVE_Z = $(Check_header_library z, zlib.h, zlibVersion)
# GIF
SUPPORT_GIF=false
CFLAGS_gif=
LDFLAGS_gif=
HAVE_GIF=
SUPPORT_GIF=false
if $(true_if_not_defined ARG_WANT_GIF)
HAVE_GIF = $(Check_header_library gif, gif_lib.h, DGifOpenFileName)
SUPPORT_GIF = $(HAVE_GIF)
if $(not $(pkg_config gif, libgif))
HAVE_GIF = $(Check_header_library gif, gif_lib.h, DGifOpenFileName)
SUPPORT_GIF = $(HAVE_GIF)
if $(SUPPORT_GIF)
LDFLAGS_gif=-lgif
export
else
failwith_if_defined(ARG_WANT_GIF, gif requested but not found)
export
if $(SUPPORT_GIF)
LDFLAGS_gif=-lgif
SUPPORTED_FORMATS+=gif
export
else
failwith_if_defined(ARG_WANT_GIF, gif requested but not found)
export
# PNG
SUPPORT_PNG=false
CFLAGS_png=
LDFLAGS_png=
HAVE_Z=
HAVE_PNG=
SUPPORT_PNG=false
if $(true_if_not_defined ARG_WANT_PNG)
HAVE_Z = $(Check_header_library z, zlib.h, zlibVersion)
HAVE_PNG = $(Check_header_library png, png.h, png_create_read_struct)
SUPPORT_PNG = $(and $(HAVE_Z) $(HAVE_PNG))
res=$(pkg_config png, libpng) # we need a separate statement to get the vars defined in pkg_config reflected.
if $(not $(res))
HAVE_PNG = $(Check_header_library png, png.h, png_create_read_struct)
SUPPORT_PNG = $(and $(HAVE_Z) $(HAVE_PNG))
if $(SUPPORT_PNG)
LDFLAGS_png=-lpng -lz
export
else
failwith_if_defined(ARG_WANT_PNG, png requested but not found)
export
if $(SUPPORT_PNG)
LDFLAGS_png=-lpng -lz
SUPPORTED_FORMATS+=png
export
else
failwith_if_defined(ARG_WANT_PNG, png requested but not found)
export
# JPEG
SUPPORT_JPEG=false
CFLAGS_jpeg=
LDFLAGS_jpeg=
HAVE_JPEG=
SUPPORT_JPEG=false
if $(true_if_not_defined ARG_WANT_JPEG)
HAVE_JPEG = $(Check_header_library jpeg, jpeglib.h, jpeg_read_header)
SUPPORT_JPEG = $(HAVE_JPEG)
res=$(pkg_config jpeg, libjpeg)
if $(not $(res))
HAVE_JPEG = $(Check_header_library jpeg, jpeglib.h, jpeg_read_header)
SUPPORT_JPEG = $(HAVE_JPEG)
if $(SUPPORT_JPEG)
LDFLAGS_jpeg=-ljpeg
export
else
failwith_if_defined(ARG_WANT_JPEG, jpeg requested but not found)
export
if $(SUPPORT_JPEG)
LDFLAGS_jpeg=-ljpeg
SUPPORTED_FORMATS+=jpeg
export
else
failwith_if_defined(ARG_WANT_JPEG, jpeg requested but not found)
export
# EXIF
SUPPORT_EXIF=false
HAVE_EXIF=
CFLAGS_exif=
LDFLAGS_exif=
SUPPORT_EXIF=false
if $(true_if_not_defined ARG_WANT_EXIF)
HAVE_EXIF = $(Check_header_library exif, exif-data.h, exif_data_load_data)
SUPPORT_EXIF = $(HAVE_EXIF)
res=$(pkg_config exif, libexif)
if $(not $(res))
HAVE_EXIF = $(Check_header_library exif, exif-data.h, exif_data_load_data)
SUPPORT_EXIF = $(HAVE_EXIF)
if $(SUPPORT_EXIF)
LDFLAGS_exif=-lexif
export
else
failwith_if_defined(ARG_WANT_EXIF, exif requested but not found)
export
if $(SUPPORT_EXIF)
LDFLAGS_exif=-lexif
SUPPORTED_FORMATS+=exif
export
else
failwith_if_defined(ARG_WANT_EXIF, exif requested but not found)
export
# TIFF
SUPPORT_TIFF=false
CFLAGS_tiff=
LDFLAGS_tiff=
HAVE_TIFF=
SUPPORT_TIFF=false
if $(true_if_not_defined ARG_WANT_TIFF)
HAVE_TIFF = $(Check_header_library tiff, tiff.h, TIFFOpen)
SUPPORT_TIFF = $(and $(HAVE_Z) $(HAVE_JPEG) $(HAVE_TIFF))
res=$(pkg_config tiff, libtiff-4)
if $(not $(res))
HAVE_TIFF = $(Check_header_library tiff, tiff.h, TIFFOpen)
# CR jfuruse: libtiff depends on jpeg and z too, which are required for -static.
# Impossible to resolve all the cases:
# the current OCaml cma has no capability to have different lib flags for dyn and static
SUPPORT_TIFF = $(HAVE_TIFF)
if $(SUPPORT_TIFF)
LDFLAGS_tiff=-ltiff
export
else
failwith_if_defined(ARG_WANT_TIFF, tiff requested but not found)
export
if $(SUPPORT_TIFF)
LDFLAGS_tiff=$(array -ltiff -ljpeg -lz)
SUPPORTED_FORMATS+=tiff
export
else
failwith_if_defined(ARG_WANT_TIFF, tiff requested but not found)
export
# XPM
SUPPORT_XPM=false
CFLAGS_xpm=
LDFLAGS_xpm=
HAVE_XPM=
SUPPORT_XPM=false
if $(true_if_not_defined ARG_WANT_XPM)
HAVE_XPM = $(Check_header_library Xpm, X11/xpm.h, XpmReadFileToXpmImage)
SUPPORT_XPM = $(HAVE_XPM)
res=$(pkg_config xpm, xpm)
if $(not $(res))
HAVE_XPM = $(Check_header_library Xpm, X11/xpm.h, XpmReadFileToXpmImage)
SUPPORT_XPM = $(HAVE_XPM)
if $(SUPPORT_XPM)
LDFLAGS_xpm=-lXpm
export
else
failwith_if_defined(ARG_WANT_XPM, xpm requested but not found)
export
if $(SUPPORT_XPM)
LDFLAGS_xpm=-lXpm
SUPPORTED_FORMATS+=xpm
export
else
failwith_if_defined(ARG_WANT_XPM, xpm requested but not found)
export
# PS
SUPPORT_PS=false
$(Check_prog_in_path gs)
PATH_GS=$(WHERE)
CFLAGS_ps=
LDFLAGS_ps=
SUPPORT_PS=false
if $(true_if_not_defined ARG_WANT_GS)
# SUPPORT_PS = $(Check_prog_in_path gs)
SUPPORT_PS = true
if $(defined ARG_PATH_GS):
PATH_GS = $(ARG_PATH_GS)
SUPPORT_PS=true
export
else
PATH_GS=$(Check_prog_in_path gs)
SUPPORT_PS=$(if $(PATH_GS), true, false)
export
if $(SUPPORT_PS)
SUPPORTED_FORMATS+=ps
......@@ -231,7 +283,9 @@ failwith_if_defined(var, msg) =
export
# LABLGTK2
SUPPORT_LABLGTK2=false
CFLAGS_lablgtk2=
LDFLAGS_lablgtk2=
SUPPORT_LABLGTK2=false
if $(true_if_not_defined ARG_WANT_LABLGTK2)
SUPPORT_LABLGTK2 = $(Check_ocamlfind_package lablgtk2)
if $(SUPPORT_LABLGTK2)
......@@ -243,7 +297,9 @@ failwith_if_defined(var, msg) =
export
# GRAPHICS
SUPPORT_GRAPHICS=false
CFLAGS_graphics=
LDFLAGS_graphics=
SUPPORT_GRAPHICS=false
if $(true_if_not_defined ARG_WANT_GRAPHICS)
# CR: ocamlfind registers graphics even if not available
SUPPORT_GRAPHICS = $(Check_ocamlfind_package_compilation graphics, Graphics)
......@@ -256,20 +312,23 @@ failwith_if_defined(var, msg) =
export
# FREETYPE
SUPPORT_FREETYPE = false
$(Check_prog_in_path freetype-config)
PATH_FREETYPE_CONFIG = $(WHERE)
CFLAGS_freetype=
LDFLAGS_freetype=
SUPPORT_FREETYPE=false
if $(true_if_not_defined ARG_WANT_FREETYPE)
# SUPPORT_FREETYPE = $(Check_prog_in_path freetype-config)
SUPPORT_FREETYPE = true
if $(defined ARG_FREETYPE_CONFIG):
PATH_FREETYPE_CONFIG = $(ARG_FREETYPE_CONFIG)
PATH_FREETYPE_CONFIG=
if $(defined ARG_PATH_FREETYPE_CONFIG):
PATH_FREETYPE_CONFIG = $(ARG_PATH_FREETYPE_CONFIG)
SUPPORT_FREETYPE = true
export
else
PATH_FREETYPE_CONFIG = $(Check_prog_in_path freetype-config)
SUPPORT_FREETYPE=$(if $(PATH_FREETYPE_CONFIG), true, false)
export
if $(SUPPORT_FREETYPE)
# println(SUPPORT_FREETYPE=$(SUPPORT_FREETYPE)!)
CAMLIMAGES_CFLAGS+= $(shell freetype-config --cflags)
LDFLAGS_freetype= $(shell freetype-config --libs)
CFLAGS_freetype= $(shell $(PATH_FREETYPE_CONFIG) --cflags)
LDFLAGS_freetype= $(shell $(PATH_FREETYPE_CONFIG) --libs)
export
if $(SUPPORT_FREETYPE)
SUPPORTED_NON_FORMATS+=freetype
......@@ -283,14 +342,8 @@ failwith_if_defined(var, msg) =
SUPPORT_RGB_TXT = $(Check_file_in_path $(PATH_RGB_TXT), rgb.txt)
PATH_RGB_TXT = $(WHERE)
# CR jfuruse: Something messy which I do not understand yet happens here!
CAMLIMAGES_LDFLAGS=$(LDFLAGS)
print_configured()
# CR jfuruse: Something messy which I do not understand yet happens here!
CFLAGS=$(CAMLIMAGES_CFLAGS)
LDFLAGS=$(CAMLIMAGES_LDFLAGS)
# for config.h
CGeneratedFiles(config.h)
section:
......
......@@ -70,10 +70,9 @@ where1(com) =
Check_prog_in_path(prog) =
ConfMsgChecking(for $(prog))
WHERE = $(where1 $(prog))
export WHERE
if $(WHERE)
ConfMsgResult(found $(WHERE))
return true
return $(WHERE)
else
ConfMsgResult(FAILED - no $(prog) found)
return false
......@@ -162,7 +161,10 @@ ConfReplaceAt(file)=
stdout = $(fopen $(file), w)
fsubst($(file).in)
case $"@\([A-Z0-9_]+\)@" g
getvar($1)
if $(defined $1)
getvar($1)
else
value false
close($(stdout))
ConfReplaceConfigH(file)=
......@@ -213,3 +215,18 @@ BuildExample(namex, modules, packages) =
###############################################################################
pkg_config(name, libname) =
ConfMsgChecking(for $(libname) by pkg-config)
if $(and $(defined this.PATH_PKG_CONFIG), $(equal 0, $(shell-code $(PATH_PKG_CONFIG) $(libname))))
# this is required since it is called in .STATIC
setvar(this.LDFLAGS_$(name), $(shell $(PATH_PKG_CONFIG) --libs $(libname)))
setvar(this.CFLAGS_$(name), $(shell $(PATH_PKG_CONFIG) --cflags $(libname)))
setvar(this.SUPPORT_$(uppercase $(name)), true)
setvar(this.HAVE_$(uppercase $(name)), true)
ConfMsgResult(found)
export
value true
else
ConfMsgResult(failed $(PATH_PKG_CONFIG) $(libname))
value false
export
========================================================
CamlImages - Objective Caml image processing library
========================================================
The latest released version is 4.1.0.
========================================================
Note: This library is currently under development.
========================================================
0. What is CamlImages ?
What is CamlImages ?
========================================================
This is an image processing library, which provides some basic
functions of image processing and loading/saving various image file
......@@ -10,35 +17,40 @@ formats. In addition the library can handle huge images that cannot be
(or can hardly be) stored into the memory (the library automatically
creates swap files and escapes them to reduce the memory usage).
1. Installation
Installation
========================================================
Read the file INSTALL.
Read the file INSTALL.txt
2. Using CamlImages
Using CamlImages
========================================================
2.1 Color models
Color models
--------------------------------------------------------
CamlImages supports the following color models:
* Rgb24 -- 24bit depth full color image
* Index8 -- 8bit depth indexed image with transparent information
* Index16 -- 16bit depth indexed image with transparent information
* Rgb24 -- 24bit depth full color image
* Index8 -- 8bit depth indexed image with transparent information
* Index16 -- 16bit depth indexed image with transparent information
For each color models, the corresponding module is provided. Use the module
Rgb24 if you want to access 24bit depth full color images, for example.
2.2 Load/Save image files and other fancy features
Load/Save image files and other fancy features
--------------------------------------------------------
CamlImages supports loading and saving of the following file formats:
Bitmap (.bmp)
Tiff (.tiff or .tif), color only
Jpeg (.jpeg or .jpg)
Png (.png)
Ppm (.pbm, .pgm, .ppm), portable pixmaps
PS (.ps, .eps), PostScript files
X Pixmap (.xpm), no saving
Gif (.gif) (not recommended)
* Bitmap (.bmp)
* Tiff (.tiff or .tif), color only
* Jpeg (.jpeg or .jpg)
* Png (.png)
* Ppm (.pbm, .pgm, .ppm), portable pixmaps
* PS (.ps, .eps), PostScript files
* X Pixmap (.xpm), no saving
* Gif (.gif) (not recommended)
* EXIF tag
For each image format, we provide a separate module. For instance,
there is a Tiff module to load and save images stored in the tiff file
......@@ -55,59 +67,60 @@ the Graphics window).
You can also draw strings on images using the Freetype library, which
is an external library to load and render TrueType fonts.
2.3 Class interface
Class interface
--------------------------------------------------------
The modules begins the letter 'o' are the class interface for CamlImages.
2.4 Image swap
Image swap
--------------------------------------------------------
When you create/load a huge image, the computer memory may not be
When you create/load a huge image, the computer memory may not be
sufficient to contain all the data. (For example, this may happen if
you are working with a scanned image of A4, 720dpi, 24bit fullcolor,
even if you have up to 128Mb of memory!) To work with such huge
even if you have up to 128Mb of memory!)
(Well, my son, the first version of this document was written around 1998,
and computers had less memory at that time.)
To work with such huge
images, CamlImages provides image swaps, which can escape part of the
images into files stored on the hard disk. A huge image is thus
partitioned into several blocks and if there is not enough free
memory, the blocks which have not been accessed recently are swapped
to temporary files. If a program requests to access to such a swapped
block, the library silently loads it back into memory.
By default, image swapping is disabled, because it slows down the
By default, image swapping is disabled, because it slows down the
programs. To activate this function, you have to modify
Bitmap.maximum_live and Bitmap.maximum_block_size. Bitmap.maximum_live
is the maximum heap live data size of the program (in words) and
Bitmap.maximum_block_size is the maximum size of swap blocks (in
words).
For example, if you do not want to use more than 10M words (that is
For example, if you do not want to use more than 10M words (that is
40Mb for a 32bit architecture or 80Mb for a 64bit architecture), set
Bitmap.maximum_live to 10000000. You may (and you should) enable heap
compaction, look at the GC interface file, gc.mli, in the standard
library for more details (you should change the compaction configuration).
Bitmap.maximum_block_size affects the speed and frequency of image
Bitmap.maximum_block_size affects the speed and frequency of image
block swapping. If it is larger, each swapping becomes slower. If it
is smaller, more swappings will occur. Too large and too small
maximum_block_size, both may make the program slower. I suggest to
have maximum_block_size set to !Bitmap.maximum_live / 10.
If you activated image swapping, cache files for unused swapped
If you activated image swapping, cache files for unused swapped
blocks will be removed automatically by Caml GC finalization,
but you may free them explicitly by hand also. The functions and methods
named "destroy" will free those blocks.
The swap files are usually created in the /tmp directory. If you
The swap files are usually created in the /tmp directory. If you
set the environment variable "CAMLIMAGESTMPDIR", then its value
replaces the default "/tmp" directory. The temporary files are erased
when the program exits successfully. In other situations, for instance
in case of spurious exception, you may need to erase temporary files
manually.
3. Miscellaneous
3.1 How do I organize my Makefile to use the library ?
Put the following line at the top of your Makefile:
include /usr/local/lib/ocaml/camlimages/Makefile.config
Where to report issues?
==========================================================
The library directory can be different if the library is installed
somewhere else. The variables COMPFLAGS_CAMLIMAGES
and LINKFLAGS_CAMLIMAGES are defined in Makefile.config; you should
add them to the compiler and linker options. A sample Makefile is
available at sample/Makefile.sample.
https://bitbucket.org/camlspotter/camlimages/issues?status=new&status=open
Image processing library
An image processing library, which provides loading and saving various
image formats with an interface for the Caml graphics library. It has
also an interface with the freetype library to draw texts using
truetype fonts.
opam-version: "1"
maintainer: "jun.furuse@gmail.com"
build: [
["omake"]
["omake" "install"]
]
remove: [
["ocamlfind" "remove" "camlimages"]
]
depends: ["ocamlfind" "lablgtk" "omake"]
archive: "https://bitbucket.org/camlspotter/camlimages/get/v4.0.1.tar.gz"
Image processing library
An image processing library, which provides loading and saving various
image formats with an interface for the Caml graphics library. It has
also an interface with the freetype library to draw texts using
truetype fonts.
opam-version: "1"
maintainer: "jun.furuse@gmail.com"
build: [
["omake"]
["omake" "install"]
]
remove: [
["ocamlfind" "remove" "camlimages"]
]
depends: ["ocamlfind" "omake"]
depopts: ["lablgtk"]
homepage: "http://cristal.inria.fr/camlimages/"
license: "LGPL-2 with OCaml linking exception"
authors: [
"Jun Furuse"
"François Pessaux"
"Pierre Weis"
]
archive: "https://bitbucket.org/camlspotter/camlimages/get/4.0.2.tar.gz"
Image processing library
An image processing library, which provides loading and saving various
image formats with an interface for the Caml graphics library. It has
also an interface with the freetype library to draw texts using
truetype fonts.
opam-version: "1"
maintainer: "jun.furuse@gmail.com"
build: [