[vtkusers] Find closest point on Mesh B from a point on Mesh A. - with off topic comments

[David Doria]

On Sun, Nov 28, 2010 at 7:15 PM, Jim Peterson <jimcp at cox.net> wrote:
> David,
> Not a problem.
> Let me try to fill this in a bit:
>
> David Doria wrote:
>>
>>
>>>
>>> 1. Could the vtkNotUsed() macro could manifest its use in the class
>>> documentation? Especially since the sole purpose of the macro is to mask
>>> out
>>> the unreferenced parameter warnings.
>>>
>>
>> Can you give a concrete example of a function where you would like to
>> see this in the Doxygen?
>>
>>
>
> Lets take EvaluateLocation() as an example. This function id documented (as
> are most functions) in the virtual definition in vtkCell.h:
>
>  // Description:
>  // Determine global coordinate (x[3]) from subId and parametric
> coordinates.
>  // Also returns interpolation weights. (The number of weights is equal to
>  // the number of points in the cell.)
>  virtual void EvaluateLocation(int& subId, double pcoords[3],
>                               double x[3], double *weights) = 0;
>
> The vtkQuadraticPyramid.cxx implementation appears to use the subId
> parameter, but only to pass it to the vtkPyramid instance:
>
> //----------------------------------------------------------------------------
> int vtkQuadraticPyramid::CellBoundary(int subId, double pcoords[3],
>                                     vtkIdList *pts)
> {
>  return this->Pyramid->CellBoundary(subId, pcoords, pts);
> }
>
> The vtkPyramid.cxx implementation says it does not use the subId parm via
> the vtkNotUsed macro:
>
> //----------------------------------------------------------------------------
> // Returns the closest face to the point specified. Closeness is measured
> // parametrically.
> int vtkPyramid::CellBoundary(int vtkNotUsed(subId), double pcoords[3],
>                          vtkIdList *pts)
> {
> ...
> }
>
> The class documentation for vtkPyramid::CellBoundary is identical to
> vtkQuadraticPyramid:CellBoundary, both refer to vtkCell documentation, and
> neither has any indication whether subId is used or not. More importantly,
> when subId is used in vtkTriangleStrip.cxx or vtkPolyLine.cxx, the problem
> of what it represents is left to the programmer.
>
> I realize this would be an ongoing process, but in my opinion, function
> parameters need to be documented and by name. what subId is used for in each
> case needs to be explicit. we should not expect documentation readers to
> have to infer that the pcoords parameter is the parametric coordinates
> described in the documentation.
>>>
>>> There are seventeen pre-built interaction styles, yet everyone seems to
>>> think they need to create a subclass of vtkInteractorStyleUser or a
>>> modification of vtkInteractorStyleTrackballCamera to meet their needs.
>>> VtkInteractorStyleSwitch provides keystroke toggles between Camera,
>>> Actor,
>>> and Joystick and Trackball (C, A, J and T respectively).
>>>
>>
>> I think the reason for subclassing the interactor styles is that it is
>> usually the most convenient place to handle keypress and mouse events:
>> http://www.vtk.org/Wiki/VTK/Examples/Cxx/Interaction/KeypressEvents
>> http://www.vtk.org/Wiki/VTK/Examples/Cxx/Interaction/MouseEvents
>>
>>
>
> your examples are exactly my point. why do a language dependent hack when we
> have observer functions of:
>
>  LeftButtonPressEvent,
>  LeftButtonReleaseEvent,
>  MiddleButtonPressEvent,
>  MiddleButtonReleaseEvent,
>  RightButtonPressEvent,
>  RightButtonReleaseEvent,
>  KeyPressEvent,
>  KeyReleaseEvent,
>  CharEvent,
>  MouseMoveEvent,
>  MouseWheelForwardEvent,
>  MouseWheelBackwardEvent,
>
> Wouldn't the language independent vtk centric solution make use of these
> observer events instead of the C++ only subclass approach?
>>>
>>> I feel the Doxygen tool generates documentation with a reasonable level
>>> of
>>> interconnection and linkage, I do think there may be some benefit in
>>> exploring options regarding the specific function and class content in
>>> the
>>> generated doc. That a careful incorporation of some content from the .cxx
>>> files may reduce the question volume on the user list.
>>>
>>
>> I think Doxygen only looks at header files. The headers should
>> completely explain the interface, which is all the user should need.
>> Many of the comments in the headers which get turned into Doxygen can
>> definitely be improved, but I don't think this requires any
>> fundamental change, just better comments :)
>>
>
> Unfortunately, the header file is rarely the thing being edited when a
> documentation significant code change is made. In my opinion again, the
> header file describes the interface to the compiler. The implementation
> logic documents the function to the programmer.
>
> Jim
>

Addressing only one of your points for the moment:

Of course we can catch these events:

http://www.vtk.org/Wiki/VTK/Examples/Cxx/Interaction/MouseEventsObserver
http://www.vtk.org/Wiki/VTK/Examples/Cxx/Interaction/KeypressObserver

The problem is that it is crazy (at least to me) in an OO language to
have to package everything up into a void* clientData to have access
to it in the observer. With the subclass approach, we can directly set
member variables (keeping their types) and access the objects that
way.

David