cpfind manual not very clear

[ChameleonScales]

Here's the pasted man cpclean :

NAME

       cpclean - Remove wrong control points by statistical methods

SYNOPSIS

       cpclean [options] input.pto

DESCRIPTION

       cpclean uses statistical methods to remove wrong control points.

       Step 1 optimises all images pairs, calculates for each pair mean and standard deviation and removes all

       control points with error bigger than mean+n*sigma.

       Step 2 optimises the whole panorama, calculates mean and standard deviation for all control points and

       removes all control points with error bigger than mean+n*sigma.

OPTIONS

       --output|-o output.pto

           Output Hugin PTO file. Default: '<filename>_clean.pto'.

       --max-distance|-n num

           distance factor for checking (default: 2)

       --pairwise-checking|-p

           do only pairwise optimisation (skip step 2)

       --whole-pano-checking|-w

           do optimise whole panorama (skip step 1)

       --dont-optimize|-s

           skip optimisation step when optimising the whole panorama

       --check-line-cp|-l

           also include line control points for calculation and filtering in step 2

       --help|-h

           shows help

AUTHORS

       Thomas Modes

"Version: 2020.0.0"                                2020-12-29                                        CPCLEAN(1)

There are a few things in it that I find a bit confusing :

• There seems to be an inconsistency in the formulations of
  

• do optimise whole panorama (skip step 1)
  and
• do only pairwise optimisation (skip step 2)
  Shouldn't the first one say
• only optimise whole panorama (skip step 1) ?
  And in any case it's not just the optimization but also the control point removal that gets skipped, so why even mention it instead of simply saying skip step 1 or 2 ?
  
• When using the --dont-optimize option on a pto, the terminal outputs
• Skipping optimisation, current image positions will be used.
  But the manual says "when optimising the whole panorama", meaning it only skips the optimisation to step 2. So wouldn't the images move in step 1 ?
  

[ChameleonScales]

I made a mistake in the title of this topic. It should say cpclean not cpfind.

[T. Modes]

ChameleonScales schrieb am Freitag, 20. Mai 2022 um 18:00:24 UTC+2:

• There seems to be an inconsistency in the formulations of
  

• • do optimise whole panorama (skip step 1)
    and
  • do only pairwise optimisation (skip step 2)
    Shouldn't the first one say
  • only optimise whole panorama (skip step 1) ?
    And in any case it's not just the optimization but also the control point removal that gets skipped, so why even mention it instead of simply saying skip step 1 or 2 ?
    

Okay, I will change this text.

• When using the --dont-optimize option on a pto, the terminal outputs
  • Skipping optimisation, current image positions will be used.
    But the manual says "when optimising the whole panorama", meaning it only skips the optimisation to step 2. So wouldn't the images move in step 1 ?
    

No. Cpclean does not change the image positions. Also with --dont-optimize it will do a pairwise optimisation, then calculate mean/sigma and do the cp clean. Afterward the results of the optimization is disregarded - so the images don't "move".

As written, only the optimisation of the whole pano is skipped.  So this option makes probably only sense in combination with --whole-pano-checking.

[ChameleonScales]

Okay, I will change this text.

Cool, thank you

No. Cpclean does not change the image positions.

I'm not very clear if you meant "generally speaking and regardless of the command arguments used" or rather "when using the --dont-optimize argument". Which is it?

In any case, to my understanding, I think the terminal output  phrase:

Skipping optimisation, current image positions will be used.

is misleading, as it only applies to step 2 and not 1.

I may get to the rest of your answer after I'm clear on those points.

[T. Modes]

ChameleonScales schrieb am Samstag, 21. Mai 2022 um 21:01:32 UTC+2:

No. Cpclean does not change the image positions.

I'm not very clear if you meant "generally speaking and regardless of the command arguments used" or rather "when using the --dont-optimize argument". Which is it?

cpclean does the following in the single steps:

step 1, for each image pair with control points

1. optimise image positions

2. calculate mean and sigma

3. remove all cp with error > mean+n*sigma

4. disregard the optimisation result

step 2: whole panorama checking

1. optimise whole panorama -> this step can be skipped with --dont-optimise

2. calculate mean and sigma

3. remove all cp with error > mean+n*sigma

4. disregard the optimisation result

So after running cpclean the image positions remain always unchanged.

[ChameleonScales]

Thanks, I think you just wrote a better version of the manual.

I think that "disregarding optimisation" part is quite important and belongs in the manual.

Also, writing it in multiline ordered lists is a bit clearer than a single phrase, as it is in the manual.