VTK:Improvement: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
 
(8 intermediate revisions by the same user not shown)
Line 4: Line 4:
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 [[Documentation Improvement|here]].
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 [[Documentation Improvement|here]].


Here are some "easy" documentation fixes:
===General===
===vtkMath===
* Add required libraries list to each class
* Pi, DoubleTwoPi, DoublePi all just say "useful constants. Maybe they could say something like "2 * 3.14159..." or 2 *\pi or something like that?
* Clearly indicate default values
* DegreesFromRadians says "Useful constants". This is incorrect. It should explain the conversion along with specify if there are/aren't bound on the input.
* Clearly explain all function parameters
* DoubleDegreesToRadians says "useful constants". This is incorrect.
 
* DoubleRadiansToDegrees says "useful constants". This is incorrect.
 
* Round(double) says "useful constants". This is incorrect.
* Floor() has no documentation at all.
* Outer(double, double, double) says "useful constants". This is incorrect.
* Norm(double, int) says "useful constants". This is incorrect.
* Perpendiculars(double, double, double, double) says "useful constants". This is incorrect. x,y,z, and theta must be explained.
* Outer2D says "useful constants". This is incorrect.
* Determinant2x2(double, double) says "Useful constants". This is incorrect.
* LUFactor3x3(double, int) says "useful constants". This is incorrect.
* LUSolve3x3(double, int,double) says "useful constants". This is incorrect.
* LinearSolve3x3(double,double,double) says "useful constants". This is incorrect.
The list goes on....


===vtkKdTree===
===vtkKdTree===
* TimingOff() says "turn ON timing"
* SetFudgeFactor should not be a function because the fudge factor is always computed in the BuildLocator or BuildLocatorFromPoints function
* SetTiming(int) says "turn on timing". It should say "turn on timing and set the interval (of what?) to the input X (the input variable is not named - also a problem).
* GetTiming says "turn on timing". This is incorrect.
* GetMinCells() says "turn on timing". This is incorrect.
* SetNumberOfRegionsOrLess has no documentation.
* SetNumberOfRegionsOrMore has no documentation.
* SetFudgeFactor has no documentation.
* RemoveDataSet says "Turn on timing". This is incorrect.
* PrintVerboseTree says "Turn on timing"
* All CreateCellLists functions have no documentation.
* GetIncludeRegionBoundaryCells/On/Off say "turn on timing". This is incorrect.
* GetCellLists functions say "turn on timing". This is incorrect.
* GetRegionContainingCell says "turn on timing". This is incorrect.
* BuildLocatorFromPoints(vtkPoints) says "turn on timing". This is incorrect.
The list goes on...


===vtkLandmarkTransform===
===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."
* GetMTime - says "Get the MTime". What is MTime? Modification time? Maybe "Get the time at which the object was last modified."


Line 50: Line 21:


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.
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?

Latest revision as of 19:15, 7 February 2010

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

  • SetFudgeFactor should not be a function because the fudge factor is always computed in the BuildLocator or BuildLocatorFromPoints function

vtkLandmarkTransform

  • 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.

Retrieved from "https://public.kitware.com/Wiki/index.php?title=VTK:Improvement&oldid=20341"