README.md 5.88 KB
Newer Older
1
2
3
4
MICMAC
======
[![Build Status](https://travis-ci.org/micmacIGN/micmac.svg?branch=master)](https://travis-ci.org/micmacIGN/micmac)

evelyne's avatar
evelyne committed
5
6
7
8
9
[Version française](LISEZMOI.md)

# Prerequisites

Some external tools need to be present on your system for Micmac to run properly :
Sebastien's avatar
Sebastien committed
10
11
12
- [make](http://www.gnu.org/software/make) for parallel processes management,
- *convert*, from [ImageMagick](http://www.imagemagick.org), for image format conversion,
- [exiftool](http://www.sno.phy.queensu.ca/~phil/exiftool) and [exiv2](http://www.exiv2.org), to read/write image meta-data,
evelyne's avatar
evelyne committed
13
14
- [proj4](http://trac.osgeo.org/proj/) for coordinate system conversion.

Maxime SEGUIN's avatar
Maxime SEGUIN committed
15
16
On Debian/Ubuntu distribution you can easily install these tools by calling this command:

Maxime SEGUIN's avatar
Maxime SEGUIN committed
17
`sudo apt-get install make imagemagick libimage-exiftool-perl exiv2 proj-bin qt5-default`
evelyne's avatar
evelyne committed
18

Maxime SEGUIN's avatar
Maxime SEGUIN committed
19
20
You can check before-hand that Micmac is able to find those programs by calling the command:

evelyne's avatar
evelyne committed
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
`bin/mm3d CheckDependencies` (in Micmac directory)

*NOT FOUND* near one of the tools indicates either the specified executable is not on your disk or it cannot be found in the
directories of the *PATH* environment variable.
There is also a special directory for tool finding which is named *binaire-aux*, in Micmac directory. When an external program
is needed, this directory is always scanned whatever the value of PATH.

## Additionnal notes for Windows

You will need [Visual C++ 2010 runtime redistribuables](http://www.microsoft.com/fr-fr/download/details.aspx?id=5555) to run pre-compiled binaries of micmac.
Both pre-compiled and compiled from source executables will need :
- [Visual C++ 2005 runtime redistribuables](http://www.microsoft.com/fr-fr/download/details.aspx?id=3387),
- and [Net Framework 2.0](http://www.microsoft.com/fr-fr/download/details.aspx?id=1639).

One of *WINDIR* or *SystemRoot* environment variable must be set to Windows' installation directory (`C:\Windows` in much cases).
This prevents Micmac from calling a `convert.exe` that is not *ImageMagick's* convert tool but a network utility used by the system.
Since Windows does not have an easy-to-use package manager, a version of *make*, *convert*, *exiftool* and *exiv2* are delivered with
the source and Windows binaries archives. They are placed in the `binaire-aux` directory.

# Compiling from the sources' archive

## Prerequisites

In addition of previously named tools, people willing to compile binaries from the source code will need to install the [cmake](www.cmake.org)
program. Linux and MacOS X users may also want to get X11 header files in order to generate graphical functionalities like *SaisieBasc*, *SaisieMasque*, etc ...
The package of X11 headers is general called `libx11-dev` under Linux distributions.
X11-based tools are not available in the Windows version.
Windows users may need Qt5 libraries to generate graphical interfaces such as *SaisieMasqQT*.

jmmuller's avatar
jmmuller committed
50
51
For recompilation optimization, [ccache](ccache.dev) is automatically used if detected.

evelyne's avatar
evelyne committed
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
## Compiling process for Linux / MacOS X

- clone the git repository : `git clone https://github.com/micmacIGN/micmac.git`
- enter 'micmac' directory : `cd micmac`
- create a directory for the build's intermediate files, then enter it : `mkdir build & cd build`
- generate makefiles using cmake : `cmake ../`
- process compilation : `make install -j*cores number*` (ex.: `make install -j4`)

## Compiling process for Visual C++ (Windows)

The first steps are the same as for a Linux/MacOS build except for the `make` call.
Instead of makefiles, *Cmake* generates a Visual C++ solution, named `micmac.sln`. Open it and compile the `INSTALL` project. 
Be sure to be in *Release* configuration, for Micmac is much faster built this way than in *Debug* mode.
Again, do not compile the entire solution but just the `INSTALL` project, otherwise compiled binaries won't be copied in the `bin` directory and this will prevent Micmac from working.

67
68
69
70
71
72
73
74
75
76
77
## Docker image
A precompiled docker image is available and ready to use:

`docker pull rupnike/micmac`

or build your own image from scratch using the existing Dockerfile:

`docker image build -t micmac:1.0 -f Dockerfile`

[![Docker Status](https://dockeri.co/image/rupnike/micmac)](https://hub.docker.com/r/rupnike/micmac/)

evelyne's avatar
evelyne committed
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
# Installation test

The website [logiciels.ign.fr](http://logiciels.ign.fr/?Telechargement,20) also provides a test dataset called `Boudha_dataset.zip`.
This file contains images and configuration files needed to compute the *Boudha* example from Micmac's documentation. By calling the script this way :

`./boudha_test.sh my_micmac_bin/`

assuming your working directory is the *Boudha* directory contained in the file, you can process all the tool-chain until dense point matching. 

'my_micmac_bin' is a path to the 'bin' directory of your installation.
	ex.: ./boudha_test.sh ../micmac/bin/
	This example assumes 'Boudha' directory (containing data) and 'micmac' (installation directory) have the same parent directory. Notice
the ending '/', it's mandatory for the script to work.
	After some computation time, you may find three 'ply' files in the 'MEC-6-Im' directory with the three parts of the dense points cloud
of the statue's head. Open the PLY files with a viewer like meshlab to check everything proceeded correctly.

# Additionnal notes

You can append the full path of the `bin` directory to `PATH` environment variable to call Micmac commands from anywhere. However, it is not necessary to add the `binaire-aux` directory to the `PATH` variable.

For Linux / MacOSX, you have to append the path to the `lib` directory to `LD_LIBRARY_PATH` in `.bashrc` to be able to use QT tools. 
Add the following line: `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/micmac/lib/`

For MacOSX, if you want to use QT tools with precompiled binaries available on [logiciels.ign.fr](http://logiciels.ign.fr/?Telechargement,20), you need to install Qt libraries for Mac from [http://download.qt-project.org](http://download.qt-project.org/archive/qt/4.8/4.8.4/qt-opensource-mac-4.8.4.dmg)