VTK:Improvement
Documentation Improvement
(If you agree with the following, vote for the improvements!!)
In my experience, the single most important factor that influences a users attitude about a software package is its ease of use. VTK provides a phenomenal collection of tools for scientific data processing and visualization. However, if a user has difficulty accessing these tools, their experience with, and therefore opinion of, the software will be less than satisfactory. Documentation is the key element which controls this difficulty level. I propose some improvements to the documentation system here.
General
- Add required libraries list to each class
- Clearly indicate default values
- Clearly explain all function parameters
vtkKdTree
- SetNumberOfRegionsOrLess has no documentation.
- SetNumberOfRegionsOrMore has no documentation.
- SetFudgeFactor has no documentation.
- All CreateCellLists functions have no documentation.
vtkLandmarkTransform
- SetTargetLandmarks/SetSourceLandmarks - both of these have the same description. One should talk about the target only and the other should talk about the source only.
- GetSource/TargetLandmarks - same description as the Set* methods. This is incorrect.
- SetModeToRigidBody has the same desciption as SetSourceLandmarks. This is incorrect.
- SetModeTo* has the same description as SetSourceLandmarks. This is incorrect.
- GetMTime - says "Get the MTime". What is MTime? Modification time? Maybe "Get the time at which the object was last modified."
vtkDecimatePro
Add this:
The SetTargetReduction function specifies how many triangles should reduced by specifying the percentage ([0,1]) of triangles to be removed. For example, if the mesh contains 100 triangles and SetTargetReduction(.90) is called, after the decimation there will be approximately 10 triangles - a 90% reduction.
Documentation To-do List
These are things that we should add to the documentation to make it clear to new users what is going on.
- vtkCutter - Need to add an image of a mesh and what happens when a vtkCutter is used to cut the mesh.
- vtkProbeFilter - What is an example of what this can actually be used to do? Provide an image?
