Hey Kay, On May 22, 2011 05:05:38 AM kfj wrote: > I had a look at the data that ended up in the repo and noticed that > parts of the README for hsi were deleted and some text was added.
I have read this modified/shortened README and IMHO it is understandable with room for improvement. I had not read the longer version you mention. I assume what is missing is what you quoted in this thread. > section (2.) affected gives some development background and explains > the changes I made to the hugin body of code to accomodate hsi/hpi and > my use of preprocessor directives to steer compilation with and > without the BUILD_HSI switch activated. OK. It is nice to have some background, but... > I feel in a README file which > lives in a source directory such information is relevant and I don't > understand why it has been deleted. ... to be honest, I find it a little bit of information overload. I miss the purpose of what has been deleted. I read this text over and over again and I am still not 100% sure what it means for me and for the project. I am sure that the information is relevant, else you would not feel as strong about communicating it. So let me ask you a few questions and see if we can flesh this out. > My main problem with hugin's body > of code is lack of documantation, not too much of it. Quality over quantity, please... > ******* begin quote ************ > Currently the only mode of distribution is source code, but this may > change now that the development branch (python_scripting) has been > merged into the default code line and compiling a version of hugin > with hsi/hpi capability is only a cmake define away. It is my hope > that compilation with this capability will become the default > eventually. The above paragraph is obsolete / obvious / redundant. HSI/PSI is now integral part of Hugin. The project distributes code tarballs and the next tarball (unless there is a need for another release candidate of 2011.0.0) includes HSI/PSI. Any updated source checkout includes HSI/PSI. So from the point of view of a person getting the source code, the only relevant bits of information are 1) the new dependencies, which have been integrated in the list of dependencies [0] 2) the new CMake switch, which is documented in INSTALL_cmake 3) the new quirks, e.g. the need to specify the location of the swig2.0 binary package, documented in platform-specific documents such as [1] > There are two levels of source you could start from. If I understand this correctly, the two levels are: 1. start completely from source 2. skip wrapper generation and start from an existing wrapper (hsiPYTHON_wrap.cxx) As I understand it, only option 1 is implemented in the repository, and it is good so. The CMake code is configured to run SWIG and generate the wrapper at build time. This insures that the wrapper is always matched with the current state of the code. Frankly, option 2 looks to me like an exercise in futility: those who do not want to deal with generating the wrapper most likely do not want to deal with source code building anyway. Give them a binary and let them script happily ever after. Those who are interested in the source are most likely interested to start completely from source. Or am I missing why you would want to overload the source distribution with a generated file and related documentation? > The remainder of this text assumes you have it all and you're going > all the way Indeed so it should be for a tarball distribution, and it makes the two previous full paragraphs loaded of details redundant. > use of SWIG is mandatory to enforce consistence > of the scripting interface with hugin, so that any change in the hugin > headers is reflected in a changed interface. You even give the compelling reason why #2 is not an option. Why bother, then? On the other hand, what you write in the following paragraphs is IMHO important. I see a purpose in it: If coders want to extend the wrapper on other sections of the codebase that are not covered yet, this is what they need to now. However, as it stands the explanation is not immediately clear. It is in the style of an experience report (a description of what you did). IMHO it would be more efficient in the style of a how-to: how do I wrap and expose a functionality/object? complemented with a list of the areas of the code that are already wrapped, and a list of areas / files worth wrapping next (in form of a todo list) it would put your work in context / perspective for those dealing with the source code. > Before I continue, let me point out the minor changes I have made in > the existing body of hugin code to integrate my work. All the changes > are encapsulated in conditional compilation directives - If the change > affects C++ code, the relevant definition is HUGIN_HSI - this is > defined globally via cmake for all compilation of the python_scripting > branch. Some C++ header files are processed by SWIG and some code in > them isn't SWIGable, those bits are taken out by #ifndef SWIG > directives, but this doesn't affect their compilation as C++ code. > Finally, some C++ headers had to be C-preprocessed for use with SWIG. > In this situation it is desirable to exclude parts of these headers, > because their precompiled equivalent would introduce large amounts of > code into the interface which isn't wanted there. So these sections, > typically containing include directives for other header files, are > excluded by #ifndef _HSI_IGNORE_SECTION, which is only defined while > the actual C-preprocessing is done. > > All code for hsi/hpi is in a separate folder called > hugin_script_interface in the src directory. The only additional code > outside this directory consists of the abovementioned compatible > changes and some cmake code to anchor hsi/hpi in the project. would you help me rephrase the above with the purpose of explaining to those who get the tarball what has been done and what is still left to do, and how to do it? > ************** end quote *************** what would deserve more attention IMHO is section 4, "play with it". We need to expand on that one and add to the manual, i.e. hook it somewhere in [2]. Now that HSI/PSI is integral part of Hugin and builders are going to distribute binaries that offer this functionality, the documentation emphasis should shift toward using HSI/PSI, building a body of example snippets to empower users that are not interested in source code matter to tinker with their scripts. Yuv [0] http://wiki.panotools.org/Development_of_Open_Source_tools#Dependencies [1] http://wiki.panotools.org/Hugin_Compiling_Ubuntu [2] http://wiki.panotools.org/Hugin
signature.asc
Description: This is a digitally signed message part.
