Installation Instructions:#

Install from Bundle#

This should be the easiest way if the bundle matches the Operating System of the user.

Download the Bundle#

Download the ZIP Bundle from the "Download" site above. The available bundles are in the "Files" tab of the site, and also at the green "Download" button of the site.
The name of the bundle tells the Stmani3 version and the OS where it runs. For the moment there is only this one:
- bundle_stmani3_v6.31_linux_mint_20.1.zip

Install the Bundle#

Expand the ZIP in any convenient folder. It will create a folder like this:

bundle_stmani3_v6.31_linux_mint_20.1
├── .............................
├── .............................
├── stmani3
├── gen-render
├── gen-html5
├── .............................
├── ....................
│   ├── ....................
│   ├── ....................
│   ├── ....................
├── ....................
│   ├── ....................
│   ├── ....................
│   ├── ....................

Run the program:
If the bundle was expanded, say, in the home folder, then the main Stmani3 program will start with this command:
```
~/bundle_stmani3_v6.31_linux_mint_20.1/stmani3
```

The batch rendering auxiliaries gen-render and gen-html5 are started in the same way.

If the programs starts successfully it will create the Configuration Folder if it does not exist already (see Configuration Folder)

Install from Source#

Download Source program:#

Get a zipped "Download Snapshot" at the "Code" tab of the "Download" site above. This is the GIT repository of the source code.

Installation of Source Program:#

Stmani3 is a Python 3.x program that has been developed and tested in a Linux-Mint computer. And I should add: in a 1920x1080 monitor. Python runs also in Windows, so in theory Stmani3 should also, but a lot of issues appear in the way. The following installation steps have been verified in a Linux Mint xcfe 19.3 system. They should work the same in Ubuntu 18.04, and other Linux systems derived from Debian, but this is not verified either.

Download Stmani3 from the "Download" link, and unzip it in some folder
Install system dependencies: Python 3.x interpreter (this version of Stmani3 does not work with Python 2.x), PIP installer, and other modules that are necessary for the installation:

sudo apt-get install python3 python3-pip virtualenv g++ python-all-dev libexiv2-dev libboost-python-dev

sudo apt-get install libimage-exiftool-perl trash-cli
cd <Stmani3 folder> (the folder where stmani3.py is)
Create a Python3 virtual environment:
virtualenv -p python3 .venv
Activate the virtual environment. A "(.venv)" prefix should appear in the prompt line:
source .venv/bin/activate
Install Python modules in the virtual environment:
pip install -r requirements.txt (see Possible Installation Issues)
Start Stmani3: ./stmani3.py or python3 ./stmani3.py

For starting Stmani3 routinely:

cd <Stmani3 folder> (the folder where stmani3.py is)
Activate the virtual environment. A "(.venv)" prefix should appear in the prompt line:
source .venv/bin/activate
Start Stmani3: ./stmani3.py or python3 ./stmani3.py

Or better use an script like this that does it all:

    #!/bin/bash 
    cd <Stmani3 folder>
    source .venv/bin/activate
    python3 ./stmani3.py

If the last steps were successful there should appear the Stmani3 main window, then the program will create the Configuration Folder if it does not exist already (see Configuration Folder)

Possible Installation Issues#

PyExiv2
The command pip install py3exiv2 (internally included in the call pip install -r requirements.txt) fails sometimes. This is because it has to be compiled which involves dependencies on several libraries, and it searches one of them: libboost with the wrong name.
This can be solved by creating a symbolic link in the library folder with the name that is actually searched by PIP:

cd /usr/lib/x86_64-linux-gnu sudo ln -s libboost_python-py36.so libboost_python36.so

- OpenCV
Some versions of OpenCV do not include the functions ORB y BFMatcher, which are necessary for automatic placement of Matching Points.
Stmani3 would still work, but could not do Automatic Alignment.
If this happened it would be necessary to install OpenCV from the source:

config.dicc
If the paths of Fonts and external programs at ~/.stmani/config.dicc were wrong, Stmani3 would send a warning. It will work without the affected functions.
It must be corrected by editing the wrong lines of config.dicc

Configuration Folder#

The first time Stmani3 runs it creates a hidden folder in the user's folder:

/home/<nombre de usuario>/.stmani = ~/.stmani. The following files are created here:

config.dicc (Configuration Options)
renders.dicc (See Dictionary of Viewers)
ultima_sesion.dicc (Parameters of the last session)

Only config.dicc is relevant for installation. This file specifies several settings:

Language of the program (Castellano or English can be chosen).
Format of Date-Time strings
Invert stereo in interlaced mode (See Interactive Rendering))
Path of the Fonts used by Stmani3 (see possible installation issues)
Path of the external programs exiftool, trash-put y trash-restore (see possible installation issues)

Initially config.dicc is created with this default content:

{   "descr_por_defecto": "descripcion-.descr",
    "formato_fecha_hora": [ "%Y-%m-%d %H:%M:%S",
                            "%Y-%m-%d_%H:%M:%S",],
    "swap_entrelazado": False,
    "fonts": {
        "Linux": {
            "path_fonts": "/usr/share/fonts/truetype/freefont", 
            "font": "FreeSerif.ttf",
            #"font": "FreeSerifItalic.ttf",
            "font_mono": "FreeMono.ttf" },
        "Windows": {
            "path_fonts": "c:\\WINDOWS\\Fonts",
            "font": "ariali.ttf",
            "font_mono": "cour.ttf" },
            },
    "apps": {
        "Linux": {
                "exiftool": "/usr/bin/exiftool",
                "trash-put": "/usr/bin/trash-put",
                "restore-trash": "/usr/bin/restore-trash",
                },
        "Windows": {
                "exiftool": "C:\\Archivos de programa\\exiftool\\exiftool.exe",
                "trash-put": None,
                "restore-trash": None,
                },
        },
    "language": "en"   # "cs" Castellano,    "en" English,
}

NOTE: The "Windows" keys suggest Stmani3 might work in Windows. Unfortunately not quite, this was just a failed attempt.

Language#

Stmani3 can work either in Castellano or English, by changing a line of ~/.stmani/config.dicc:
- Castellano: language": "cs"
- English: language": "en"

Folder Organization#

A Single Work Folder#

All initial image files must be in a single folder.
The files created by Stmani3 (*.pair, *.lstpair, *.descr) are also in that folder
NOTE: The most important Stmani3 output are the small text files *.pair. Each *.pair corresponds to a pair of images (though they may also be a single image), and it contains all the Angular Alignment parameters.
The *.pair file and its corresponding images are the base to render final stereo images in a variety of formats and sizes (See Rendering)
The rendered images are loaded in a temporal folder.

Initial Preparation of images in Work Folder:#

Single camera stereo (cha-cha, W3, et al.): Load all images without renaming
Stereo Rigs with two cameras. Renaming is necessary to identify the side:
- SDM Rigs: Ensure the names include STL / STR keys (Should be generated by SDM)
- Others: Images need to be renamed:
  - Left camera: Add appendix "-I" or "-L"
  - Right camera: Add appendix "-D" ó "-R"

Temporary Folder#

It may be /tmp/stmani/ or /var/tmp/stmani/ It is used to store the rendered images.
NOTE: This folder is erased periodically by the system.

Trash Folder#

In Linux Mint: /.Trash-nnnn/ where nnnn is the User-Id number.
It is placed in the root of the partition where the Work Folder belongs

The Configuration and Trash folders are shown by clicking the button "Help" -> "About Stmani3"

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search