"""
 file: map_utils.py

 This file contains generic utility functions
 for use in the openrpg mapping system
"""

import math
"""
 distance_between()
 Returns the distance between two points
"""
def distance_between( x1, y1, x2, y2 ):
   "Returns the distance between two points"
   dx = x2 - x1
   dy = y2 - y1
   return math.sqrt( dx*dx + dy*dy )

"""
 proximity_test()
 Tests if 'test_point' (T) is close (within 'threshold' units) to the
 line segment 'start_point' to 'end_point' (PQ).

 The closest point (R) to T on the line PQ is given by:
    R = P + u (Q - P)
 TR is perpendicular to PQ so:
    (T - R) dot (Q - P) = 0
 Solving these two equations gives the equation for u (see below).

 If u < 0 or u > 1 then R is not within the line segment and we simply
 test against point P or Q.
"""
def proximity_test( start_point, end_point, test_point, threshold ):
   "Test if a point is close to a line segment"
   x1,y1 = start_point
   x2,y2 = end_point
   xt,yt = test_point
   x1 = float(x1)
   x2 = float(x2)
   y1 = float(y1)
   y2 = float(y2)
   xt = float(xt)
   yt = float(yt)

   # Coincident points?
   if x1 == x2 and y1 == y2: d = distance_between(xt, yt, x1, y1)
   else:
       dx = x2 - x1
       dy = y2 - y1
       u = ((xt - x1) * dx + (yt - y1) * dy) / (dx*dx + dy*dy)
       if u < 0: d = distance_between(xt, yt, x1, y1)
       elif u > 1: d = distance_between(xt, yt, x2, y2)
       else:
           xr = x1 + u * dx
           yr = y1 + u * dy
           d = distance_between(xt, yt, xr, yr)
   return d <= threshold