bugGNU Octave - Bugs: bug #45747, image package: Inconsistent...

 
 

bug #45747: image package: Inconsistent argument names in cp2tform, maketform, and tformfwd

Submitter:  Rafael Laboissière <rlaboiss>
Submitted:  Thu 13 Aug 2015 08:42:12 PM UTC
   
 
Category:  Octave Package Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * other Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Wed 16 Sep 2015 12:15:27 PM UTC, comment #5: 

Thank you. I have pushed those changes.

Carnë Draug <carandraug>
Group Member
Thu 10 Sep 2015 09:06:20 PM UTC, comment #4: 

I attached 4 separate patches that I hope make the documentation for transform related functions easier to understand.
I tried to consistently use input/output space terminology. I also replaced input/output coordinates in the examples by uv/xy.

(file #34848, file #34849, file #34850, file #34851)

Pantxo Diribarne <pantxo>
Group Member
Mon 24 Aug 2015 08:16:13 PM UTC, comment #3: 

I must say I fully agree with the fact that the doc. for those functions should be overhauled. I have already started doing the job and I will report back here.

Pantxo Diribarne <pantxo>
Group Member
Mon 24 Aug 2015 05:56:13 PM UTC, comment #2: 

Adding Pantxo Diribarne, author of this functions to CC.

Carnë Draug <carandraug>
Group Member
Thu 13 Aug 2015 09:22:21 PM UTC, comment #1: 

Erratum: The correct link to the bug report against the Debian package is https://bugs.debian.org/794780

Rafael Laboissière <rlaboiss>
Thu 13 Aug 2015 08:42:12 PM UTC, original submission:  

I am reporting below some comments made by Francesco Potortì in the context of Bug#794780, filed against the Debian pacakge octave-image.  There are apparently incosistencies in the way arguments are named in functions cp2tform, maketform, tformfwd, and tforminv.

I am transcribing almost verbatim what Francesco wrote.  I did not check carefully his claims.  Please, feel free to close this bug report if you think the comments are not relevant.

Rafael Laboissière

=================================================
From: Francesco Potortì
Date: 2015-08-13


 -- Function File: T = cp2tform (RW_PT, AP_PT, TRANSTYPE)
 -- Function File: T = cp2tform (RW_PT, AP_PT, TRANSTYPE, OPT)

     Returns a transformation structure T (see "help maketform" for the
     form of the structure) that can be further used to transform
     coordinates from one space (here denoted "RW" for "real world") to
     another (here denoted "AP" for "apparent").  The transform is


As you can read, the two reference systems are called here "real world" and "apparent".


 -- Function File: T = maketform (TTYPE, TMAT)
 -- Function File: T = maketform (TTYPE, INC, OUTC)
 -- Function File: T = maketform ("custom", NDIMS_IN, NDIMS_OUT,
          FORWARD_FCN, INVERSE_FCN, TDATA)
     Create structure for spatial transformations.


Here no explicit name is given to the two reference systems, but from the formal arguments it is apparent that they are intended as "in" and "out".


 -- Function File: [UV] = tformfwd (T, XY)
 -- Function File: [U, V] = tformfwd (T, X, Y)

     Given to dimensionnal coordinates from one space, returns two
     dimensionnal coordinates in the other space, as defined in the
     transform structure T.  Input and output coordinates may be gigen
     either as a n-by-2 arrays, or as two n-by-1 vectors.


Here the two reference systems are just anonymous, so no semantic is even suggested, and they are called "one" and "the other".

So we have three different naming conventions for three functions which are strictly related.  Since maketform is the basis function, and the one that choses the naming of the fields in the Tform, probebaly the "in" and "out" convention should be used in all description strings.

Now that I notice it, the tforminv function has the same exact description as the tformfwd function, which makes no sense.  The typos are the same, and besides it should at least mention that while the tformfwd uses the "forward_fcn" matrix inside the Tform, tforminv uses the "inverse_fcn" matrix in the Tform.

Rafael Laboissière <rlaboiss>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #34848:  doc_cp2tform.patch added by pantxo (5KiB - text/x-diff)
file #34849:  doc_imtransform.patch added by pantxo (4KiB - text/x-diff)
file #34850:  doc_maketform.patch added by pantxo (5KiB - text/x-diff)
file #34851:  doc_tforminv_fwd.patch added by pantxo (3KiB - text/x-diff)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by pantxo (Posted a comment)
  • -email is unavailable- added by carandraug (Pantxo Diribarne)
  • -email is unavailable- added by rlaboiss (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 8 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2015-09-16 carandraug StatusNone Fixed
        Open/ClosedOpen Closed
    2015-09-10 pantxo Attached File- Added doc_cp2tform.patch, #34848
        Attached File- Added doc_imtransform.patch, #34849
        Attached File- Added doc_maketform.patch, #34850
        Attached File- Added doc_tforminv_fwd.patch, #34851
    2015-08-24 carandraug Summaryoctave-image: Inconsistent argument names in doc strings image package: Inconsistent argument names in cp2tform, maketform, and tformfwd
        Carbon-Copy- Added -email is unavailable-

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code