OpenCVMeetingNotes/Minutes 2009-10-29

Agenda

Documentation

Minutes

• Large amount of documentation
• Probably 2 weeks just to do anything to the whole corpus
• Need to merge a single document with the APIs in
  • Vadim: C document will not change much
    • Won't change much
    • Main reference manual would be shorter with less conditionals
  • James:
    • Uses C document a lot and there's lots of document bugs there (bugs, broken links, inaccurate text, missing info)
    • Don't want to freeze this as is
• V: Put most of things to new document, old API could mostly link to the new document
• J: That's one way of having "one" document, but bad for users
• V: Old style interface is getting obsolete
• J: 3.0, C is deprecated
• V: Old API will stay past 3
• J: Was using cvCalibrateStereo
  • A lot of this document is common to C, C++, Python
  • meaning of enums etc. Everyone will want to know common

  • value of the function description is >> call signature

• V: function descriptions can stay, but formulas, descritions can
• J: This will be a pain for users to keep multiple links
• V: Documentation can get quite big
  • Argus is switched to new API
  • Would just do good documentation for new API
• J: Then what's the plan for C documentation?
  • V: Function and parameter descriptions as is, rest point to new API in C++ reference
• J: Most of the complexity is in the parameter descriptions. Where would these description reside
  • V: feature not bug, because if C++ extends API, then it can change and C doesn't change
  • J: Bugs in documents as well as C
• V: Most users will go to new API in 1-2 years

• Issue:

  • 2 docs (C++ and C) vs a merged one with conditionals
    • Advantage is simpler main doc
    • Disadvantage is maintain 2 version
• Maintaining semantics
  • New API may get extra parameters
• But, lots of work needs to be done to improve the documentation
  • So its not the case that the C document can be locked down
  • Might be many 1000's of changes to the documents
    • That gets hard with 2 documents
• Main issue is duplication: something in 2 places is harder to maintain
  • Wiki and HTML slowly drifted, want to avoid this drift again

  • CxCore, CvRef -- all in big files, maybe if these are split into smaller blocks

    • Camera calibration for example, the API is roughly the same between C and C++
    • Feature descriptors are only C++
  • Maybe splitting the documents that are mostly different, but if only parameter differences, then makes sense for 1 function
  • For example, HOG is just in C++
  • Pulling new functions into C++/Python only files

• V: CvAdd has large differences, allows arbitrary. C is overloaded. Default parameters

  • In C++ can't default references This causes differences. Python uses output tuples

Platex is quite fragile and so we need to make sure that documents

Decision

• We should get someone
• We should bring the Python and C++ together.
  • Numerical python ... use their numerical types so that we can make use of python's optimization etc functionality
  • Can replace a lot of cxcore
• MLL (C and C++) can be done by Maria
• Cluster docs into join and separate groups
• Merge functions listed in Vadim's email (functions with significant differences)
  • This will set the style
  • Someone else do this for the rest
• Make sure the latex documents still builds

Action Items

Gary

• Find someone who can do latex to merge and divide C and C++
  • Produce a file with conditionals for all 3 target languages

James

• Take functions Vadim listed (that have significant API differences C vs C++) to set the style of how to document

Vadim

• Cluster the doc files into "Conditionals" and "Separate" files
• Document the undocumented new functions

OpenCVMeetingNotes