Re: [Tcllib-devel] Functions in ::math::geometry

[Larry W. V. <lv...@ca...>]

From: Christian Heide Damm <da...@id...>

> # geometry.tcl --
> # See the file "license.terms" for information on usage and redistribution
> # of this file, and for a DISCLAIMER OF ALL WARRANTIES.

Remember that the current Tcllib policy is for code included to be covered 
in a BSD or very VERY similar license...

> 
> # ::math::geometry::calculateDistanceToMultiline
> #
> #       Calculate the distance between p and multiline.
> #
> # Arguments:
> #       p           a point (x,y)
> #       multiline   a list of points (x,y) constituting a line

How many points in multiline?  How many lines (multiline sounds like
multiple lines...)


> #
> # Results:
> #       dist        the smallest distance between p and any point
> #                   on the multiline

What is dist?  a single floating point value?

> #
> proc ::math::geometry::calculateDistanceToMultiline {p multiline} {
>     ...
> }
> 
> # ::math::geometry::findClosestPointOnMultiline
> #
> #       Return the point on $multiLine which is closest to $p.
> #
> # Arguments:
> #       p           a point (x,y)
> #       multiline   a list of points (x,y) constituting a line
> #
> # Results:
> #       q           the point on the multiline that has the smallest
> #                   distance to p
> #

I assume that q is also an x and y?  Is it one of the points listed in
multiline, or a point calculated to exist on the line that includes the
points of multiline.


> # ::math::geometry::calculateDistanceToLineSegmentImpl
> #
> #       PRIVATE FUNCTION USED BY OTHER FUNCTIONS.


So this function will not be one that developers would be needing to call
in general?

> # ::math::geometry::calculateDistanceToLine
> #
> #       Calculate the distance between C and the infinite line
> #       that goes through A and B.

How is this different than the first distance calculating?

> # ::math::geometry::length
> #
> #       Find the length of the line (x1,y1),(x2,y2),...,(xn,yn).


I assume that this is "find the length of the line segment
from x1,y1 -> xn,yn" ?



> # ::math::geometry::angle
> #
> #       Calculates angle from the horizon to the line (x1,y1)->(x2,y2).
> #
> # Arguments:
> #       x1,y1,x2,y2   the line
> #
> # Results:
> #       angle         the angle between the line (0,0)->(1,0) and (x1,y1)->(x2,y2).
> #                     angle is in 360-degrees going counter-clockwise
> #

Is angle returned in degrees?  radians?  some other unit?

> # ::math::geometry::findLineSegmentIntersection
> #
> #       Returns the point where the two line segments intersect.
> #       Note: may also return "coincident" and "none".
> #
> # Arguments:
> #       line1        the first line segment
> #       line2        the second line segment

What are these arguments?  2 or more x,y pairs?

> #
> # Results:
> #       p            the point where line1 and line2 intersect.


So p's value is a list, consisting either of one of two words or an x,y pair?



> # ::math::geometry::findLineIntersection {line1 line2}
> #
> #       Returns the point where the two lines intersect.
> #       Note: may also return "coincident" and "none".
> #
> # Arguments:
> #       line1        the first line
> #       line2        the second line

What are these arguments?  2 or more x,y pairs?


> unsure_about_these {

unsure in what way - whether you will do them?  whether they belong here?
whether these are the right names?  whether these are the right interfaces?

-- 
Never apply a Star Trek solution to a Babylon 5 problem.
Larry W. Virden <mailto:lv...@ca...> <URL: http://www.purl.org/NET/lvirden/>
Even if explicitly stated to the contrary, nothing in this posting should 
be construed as representing my employer's opinions.
-><-