align_image_stack parameters

[Chris]

I am using align_image_stack to align 2 images for processing into a 3D image.

There is documentation https://wiki.panotools.org/Align_image_stack but the page states that ““This article is incomplete. You can help Panotools Wiki by expanding it.”

The descriptions are brief and I’m not sure I completely understand them all. It is not clear which options are mutually exclusive.

I’ve added speculative explanations to that table and below it added another with speculations about the relationships between the parameters. I would appreciate having explanations added where they are missing and errors corrected

If I get some clear answers, they could be useful for updating the wiki page.

[T. Modes]

Chris schrieb am Dienstag, 9. April 2024 um 00:51:28 UTC+2:

I am using align_image_stack to align 2 images for processing into a 3D image.

There is documentation https://wiki.panotools.org/Align_image_stack but the page states that ““This article is incomplete. You can help Panotools Wiki by expanding it.”

The descriptions are brief and I’m not sure I completely understand them all. It is not clear which options are mutually exclusive.

I expanded the wiki page. Hopefully this make some more clear.

All (or most) of the switches are not mutually exclusive, they can be used together.

By posting only PNG images you make it more difficult to answer to some of your points.

e.g. -l switch refer to linear color space. This has totally unrelated to rectilinear images, also fisheye images can be in linear color space. So this switch is not redundant.

[Chris]

Thanks, I will have a look at your information. I tried to post it as two tables, but couldn't find any way to do so. The only way I could think of was a screenshot. Here it is as two lists:

OPTIONS/Function/Explanation/Group

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

Modes of operation:

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

-p file Output .pto file (useful for debugging, or further refinement) 

----- 

-

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

-a prefix Output aligned images as prefix_xxxx.tif

-----

Output an image for each input image, using the prefix shown. 

-

1x

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

-o output Align images and merge them to HDR, generate output.hdr

----- 

Create one High Dynamic Range output file, named as shown.

1x

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

Modifiers:

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

-v Verbose, print progress messages. Repeat for higher verbosity

-----

Does “Repeat…” mean that -v -v would output more details than -v?

-

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

-e Assume input images are full frame fish eye (default: rectilinear)

-----

Specifies a special image geometry.

3x

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

-t num Remove all control points with an error higher than num pixels (default: 3)

----- 

Alter precision, maybe improve alignment but possibly make it impossible to match some images.

5x?

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

--corr=num Correlation threshold for identifying control points (default: 0.9) 

----- 

Alter precision, maybe improve alignment but possibly make it impossible to match some images. 

5x?

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

-f HFOV Approximate horizontal field of view of input images, use if EXIF info not complete 

----- 

No idea.

-

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

-m Optimize field of view for all images, except for first. Useful for aligning focus stacks with slightly different magnification. 

-----

 No idea. 

3x?

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

-d Optimize radial distortion for all images, except for first. 

----- 

No idea.

3x

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

-i Optimize image center shift for all images, except for first.

-----

No idea.

3x

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

-x Optimize X coordinate of camera position 

-----

 No idea. 

3x

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

-y Optimize Y coordinate of camera position

 ----- 

No idea. 

3x

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

-z Optimize Z coordinate of camera position 

----- 

No idea.

3x

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

-S Assume stereo images - allow horizontal shift of control points. 

----- 

See -A 

2x?

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

-A Align stereo window - assumes -S Does “Assumes -S” mean “assumes you are also using -S”? So -S is mandatory with 

----- -

A?

2x

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

-P Align stereo window with pop-out effect - assumes -S 

----- 

See -A. 

2x

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

-C Auto crop the image to the area covered by all images

----- 

-

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

-c num Number of control points (per grid) to create between adjacent images (default: 8) 

----- 

Can select more or less precision by creating more control points per grid square.

6+

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

-l Assume linear input files 

----- 

Parameter-e states “(default: rectilinear)”. 

So isn’t this parameter redundant? Or does it mean something else? 

3x

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

-s scale Scale down image by 2^scale (default: 1 [2x down-sampling+)

 -----

 Reduce output image size in the chosen ratio to the input images.

-

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

-g gsize Break image into a rectangular grid (gsize x gsize) and attempt to find num control points in each section (default: 5 [5x5 grid+) 

----- 

Spread control points evenly over image by dividing it into squares and having same number of control points in each. Where does num come from, is it -c num?

6+

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

--distortion Try to load distortion information from lens database

 -----

Presumably if data is available, AIS uses it to try to compensate for the distortion. What happens if there is none or it’s invalid?

-

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

--use-given-order Use the image order as given on the command line. (By default images will be sorted by exposure values.)

 ----- 

Does not affect 3D processing as images are identified as right and left by their order on the command line? 

2x

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

--gpu Use GPU for remapping 

-----

 What happens if there’s no GPU or it’s unsuitable? 

-

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

-h Display help summary. 

-----

-

======================================================================

Group/Probable Relationship/Parameters/Function

1x

Mutually exclusive

-p or -o

Output file(s)

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

2x

Mutually exclusive

-A or -P

-S?

--use-given-order

Stereo image type

It’s not clear whether -S must be used when -A or -P is, or whether it will be included automatically when -A or -P is.

What is the difference between -A and -S?

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

3x

Mutually exclusive

-d -i -x -y -z

Which coordinate to optimise?

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

4x

Mutually exclusive

-e -l

Image geometry

What’s the point of -l if the default is rectilinear?

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

5+

If -g is used, -c must be used too to supply num

-c -g

Affect precision.

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

6x

Mutually exclusive?

-t --corr

Affect precision

What’s the difference between -t and -corr?

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

-

Unrelated to other parameters

-p -v -h

-f -C -s --gpu

--distortion

Tools

Various

[T. Modes]

Chris schrieb am Dienstag, 9. April 2024 um 20:14:04 UTC+2:

-v Verbose, print progress messages. Repeat for higher verbosity

-----

Does “Repeat…” mean that -v -v would output more details than -v?

yes,

 

-l Assume linear input files 

----- 

Parameter-e states “(default: rectilinear)”. 

So isn’t this parameter redundant? Or does it mean something else? 

This refers to linear color space, this has nothing to do with rectilinear projection. So it is not redundant.

 

--distortion Try to load distortion information from lens database

 -----

Presumably if data is available, AIS uses it to try to compensate for the distortion. What happens if there is none or it’s invalid?

If no data is available, no distortion is corrected. 

 

--use-given-order Use the image order as given on the command line. (By default images will be sorted by exposure values.)

 ----- 

Does not affect 3D processing as images are identified as right and left by their order on the command line? 

Not sure what you mean with 3D processing. 

 

--gpu Use GPU for remapping 

-----

 What happens if there’s no GPU or it’s unsuitable? 

Normally it should stop with an error message. But I have no test system without GPU. No sure if this is from any practical relevance.

Group/Probable Relationship/Parameters/Function

1x

Mutually exclusive

-p or -o

Output file(s)

No, they can be combined.

 

2x

Mutually exclusive

-A or -P

-S?

Stereo image type

It’s not clear whether -S must be used when -A or -P is, or whether it will be included automatically when -A or -P is.

-A and -P add automatically switch -S internal.

What is the difference between -A and -S?

See the linked page http://vndlinuxphoto.blogspot.com/2011/01/stereo-image-alignment-in-hugin.html

3x

Mutually exclusive

-d -i -x -y -z

Which coordinate to optimise?

Can be combined in any combination.

4x

Mutually exclusive

-e -l

Image geometry

What’s the point of -l if the default is rectilinear?

see above, both are unrelated.

[Chris]

Great! The webpage is far more informative now, putting it into sections helps a lot.

I’m only interested in 3D image processing, but I’ve had a look at all the options in case they might be relevant and I hope my further questions might help someone else. I'll look at the 3D ones later.

--align-to-first

...This implies also the --use-given-order option.

Does this mean

     “Assumes you have also used –use-given-order.” If so, what would happen if you hadn’t?

Or

      “This will also set/activate/turn-on the -use-given-order option.”

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

-f HFOV ...use if EXIF info not complete 

If neither is available what happens?

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

-l Assume linear input files are in linera colour space. 

Is the default gamma colour space?

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

--distortion ...the lens distortion...is done 

Perhaps this means “...the lens distortion correction...are done...” 

Presumably if there is no distortion information or it’s invalid, this process is just abandoned.

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

-g gsize ...attempt to find num control points…

i assume that the value of -num comes from -c num if it is set, otherwise it is the default of 8 mentioned in that section.

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

Optimisation phase

How do “(yaw, pitch and roll) “ relate to x, y,z?

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

-m -d -i -x -y -z Optimize field of view

I assume one might as well always set all of -m -d -i -x -y -z in order to optimise everything . Unless you mean prioritise, in which case:

      All of them will be optimised, but -X will be prioritised.

Or

     -X will be optimised, the rest ignored.

[Chris]

--gpu
Use GPU for remapping

Presumably if there is no GPU or it’s unsuitable, the CPU is used instead.

I'll look at the 3D imaging later.

[T. Modes]

Chris schrieb am Donnerstag, 11. April 2024 um 10:20:43 UTC+2:

Great! The webpage is far more informative now, putting it into sections helps a lot.

I’m only interested in 3D image processing, but I’ve had a look at all the options in case they might be relevant and I hope my further questions might help someone else. I'll look at the 3D ones later.

--align-to-first

...This implies also the --use-given-order option.

The -use-given-order is automatically activated. (But adding it manually makes no difference.)

-f HFOV ...use if EXIF info not complete 

If neither is available what happens?

It will use a sensible default value - see output of the program.

-l Assume linear input files are in linera colour space. 

Is the default gamma colour space?

Yes.

 

Optimisation phase

How do “(yaw, pitch and roll) “ relate to x, y,z?

They all together describe the position and direction of the camera in space.

See coordinate system of panotools.

-m -d -i -x -y -z Optimize field of view

I assume one might as well always set all of -m -d -i -x -y -z in order to optimise everything .

No, that' s totally wrong. The more parameter you try to optimize the more precise and better distributed control points you need. 

Especially optimization of x/y/z can often be fragile and should only be added when really needed.

Instead of the command line the best would be to start with the pto file and optimize then in the GUI. First start with only the basic parameters and then add one parameter after the other and after each optimization run check the result in the preview window.

 

[Chris]

--align-to-first

…This implies also the --use-given-order option.

To me as a native English speaker this is ambiguous but probably means:

“This means you must also use the –use-given-order option.”

If so, what would happen if you hadn’t?

But I suspect the intended meaning might have been

“This also sets/activates/turns-on the --use-given-order option.”

Looks like an option best avoided due to uncertainty about what it does.

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

--distortion Hopefully if there is no distortion information or it’s invalid, this process is not performed – rather than the program going into an endless loop or aborting.

I won’t use this option as I don’t want to risk the program hanging or aborting.

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

-g gsize

Break image into a rectangular grid (gsize x gsize) and attempt to find num control points in each section (default: 5 [5x5 grid+)

Should I assume that the value of num comes from -c num if that option is used, otherwise it is the default of 8 mentioned under -c?

I won’t use this option as I don’t want to risk the program hanging or aborting if my assumptions about num are incorrect.

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

Optimisation phase

I assume x means adjustment along the horizontal pitch axis, y to adjustment on the vertical yaw axis and z to adjustment on the “out of the window” roll axis.

Shouldn’t it be “Optimize correction of radial distortion”?

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

--gpu Since there is no information about what might happen if the GPU was unsuitable or missing (I have a GPU so can’t test that), I won’t use this option as I don’t want to risk the program hanging or aborting.

That's it with the questions :)/

[Chris]

This comes from the other thread as it probably belongs here:

-S Assume stereo images - allow horizontal shift of control points. Adds all control points as "horizontal lines".
-A Align stereo window - assumes -S. Adds one "normal" control point that is the nearest point, so that everything will appear behind the display plane.
-P Align stereo window with pop-out effect - assumes -S. Adds one "normal" control point that is the nearest point from the border areas, so that the center of the image may appear in front of the display plane.

The language is a little ambiguous here - “assumes -S “ Does this mean

-      “Assumes you have also used the –-S parameter?” If not what would happen?

Or

-      “This will also set/activate/turn-on the -S option.”

[Chris]

Moved from the other thread:
T.Modes "But you repeat often the same phrases: assumes options or implies options means in this context that the corresponding option [was?] automatically activated/set and does not need to [be?] set manually."

That's because you haven't clearly explained them before. Those phrases are meaningless on their own. I continue to ask for the documentation to be clarified so that anyone else reading it will be clear about what is meant - without having to discover and read through this whole thread.

There might be exceptions, but English usually needs an explanatory phrase after "assumes" or "implies", or it doesn't make sense. Certainly in this case they do. For example
Implies that x has been done.
Assumes that z will be done.
In fact I can't see how either "implies" or "assumes" can be used in this context.

Alternatively "This option will also set/activate/turn-on X"  uses simple English and the meaning is quite clear.

Why are you reluctant to alter the original phrases? Were they written by someone with high status within the Panotools heirarchy who you do not wish to offend by criticising his/her English? 

I saw mention on one documentation page of an author with a name that suggested that he was a French speaker, and you are a German speaker. With respect, as a native speaker of English, I think my grasp of the English language is naturally going to be deeper than yours.

I have no axes to grind over this, I just wish to make this amazing software more accessible to ordinary users by ensuring that its functions are clearly exlained.

[Chris]

T.Modes, Wie du sicher weißt, bedeutet das deutsche Wort "Gift" etwas ganz anderes als das englische Wort "gift" :).
Vielleicht sind die Worte "impliziert" und "implies" falsche Freunde - sie haben etwas unterschiedliche Bedeutungen.

(As I am sure you are aware, the German word "Gift" means something quite different to the English word "gift" :).
Perhaps the words "impliziert" and "implies" are false friends - they have rather different meanings.)

[Greg 'groggy' Lehey]

On Wednesday, 17 April 2024 at 23:39:07 -0700, Chris wrote:
> T.Modes, Wie du sicher weißt, bedeutet das deutsche Wort "Gift" etwas ganz
> anderes als das englische Wort "gift" :).
> Vielleicht sind die Worte "impliziert" und "implies" falsche Freunde - sie
> haben etwas unterschiedliche Bedeutungen.
>
> (As I am sure you are aware, the German word "Gift" means something quite
> different to the English word "gift" :).
> Perhaps the words "impliziert" and "implies" are false friends - they have
> rather different meanings.)
> On Wednesday, April 17, 2024 at 7:33:51 AM UTC+1 Chris wrote:

Chris, I've seen a lot of messages from you. This one seems to be the
second one with identical content. And most of them seem to have
nothing to do with the software.

If you feel that you have to attack T.Modes, please do it privately.

Greg
--
Sent from my desktop computer.
Finger groo...@gmail.com for PGP public key.
See complete headers for address and phone numbers.
This message is digitally signed. If your Microsoft mail program
reports problems, please read http://lemis.com/broken-MUA.php

[Frédéric Da Vitoria]

Le 18/04/2024 à 09:19, Greg 'groggy' Lehey a écrit :

On Wednesday, 17 April 2024 at 23:39:07 -0700, Chris wrote:

T.Modes, Wie du sicher weißt, bedeutet das deutsche Wort "Gift" etwas ganz
anderes als das englische Wort "gift" :).
Vielleicht sind die Worte "impliziert" und "implies" falsche Freunde - sie
haben etwas unterschiedliche Bedeutungen.

(As I am sure you are aware, the German word "Gift" means something quite
different to the English word "gift" :).
Perhaps the words "impliziert" and "implies" are false friends - they have
rather different meanings.)
On Wednesday, April 17, 2024 at 7:33:51 AM UTC+1 Chris wrote:

Chris, I've seen a lot of messages from you.  This one seems to be the
second one with identical content.  And most of them seem to have
nothing to do with the software.

If you feel that you have to attack T.Modes, please do it privately.

Greg,

Chris has repeatedly stated that his questions and remarks were about the documentation. While I agree they don't have anything to do with the coding, they do have to do with the software because documentation IMO should be considered as being part of the software. If a documentation tells me something (I am not speaking of the Hugin documentation here) and the software does something else, then this is a bug. I agree this would be a documentation bug, not a coding bug, but it would still be a bug. Or maybe the word "bug" is not appropriate here. Anyhow documentation issues should be addressed just like coding bugs should be fixed.

About your second paragraph: I don't feel that Chris has attacked Thomas. I saw Chris insisting on documentation issues. It happens that Thomas was almost the only one to answer, but I did not feel anything personal in Chris' mails.

I am glad that someone is checking the exact formulation of the documentation. I don't know who wrote the documentation (although I would not be surprised if it was Thomas), but I know that developers are seldom good documentation writers. I am a software developer, I have tried to write documentation and I don't think I ever achieved something which was simultaneously short enough, clear enough and unambiguous. It is very difficult for a developer to realize that people could understand what he wrote differently from what he meant. It is even more difficult for him to find all the sentences where such gap could exist.

I know that all the documentation was written by volunteers doing it on their free time (just like the code). Improving the documentation takes time, and the resources are limited. I guess that Thomas enjoys much more coding than writing documentation (I do!).

I enjoyed this discussion up to now because it has taught me a few things about English. And I would appreciate improving the documentation in this way because I am always wary about what I am understanding from a documentation written by someone whose native language is probably not English, even more so because it is not mine either.

[Chris]

davi...@gmail.com

Thank you for your careful reading of my posts, your understanding of the reason behind my questions and your support.

Chris