# WHAT
#        This is a very basic wrapper for the closestIntersection function of MFnMesh in Python
# form so you can load it as a plugin node and use that node as you please.
# MFnMesh.closestIntersection shoots a ray from a source position, along a vector, and tells
# you if you hit the mesh you gave it to test against.  There is a maxParam which is the maximum
# radius from the ray source to check against.

# The commenting is for someone like me, right now, Apr1, 2008 (good with MEL, but VERY new to python
# and Maya's API). If you're like that, you might be able to pick up some information about python and
# plugins in a manner that might not otherwise be an obvious way for folks who already know all this
# stuff to try and teach it. I tell you - us MEL guys need to be the target audience with this python
# stuff.

# USAGE
#     To create the node : createNode oeRay

#     Set the node a ray source position, ray direction, a collider (intersection mesh), and
# maxParam (maximum intersect search radius), and a choice for if you want the failure-state
# (no collision found / "return to source") "out position" value to be at it's farthest reach
# (maxParam along vector), or back where it originated (ray source). Returns if there is any
# collision at all, the intersect point, (or farthest reach along that direction) closest face
# to the intersection, and closest vertex to the intersection.

# AETemplate
#     AEoeRayTemplate.mel should be packed along with the .py. It is an attribute editor template
# to arrange and organize the attributes for this node a little better.  The plugin will work the
# same without this, but "looks" better with it.

# NOTES

#        outFace and outVertex each return a valid index ONLY in case of a successful intersection.
# If there was no intersection found, they return a value of -1.  This is because if we "try"
# to return a result otherwise, it comes back with nonsense, and isn't usable.  This allows
# a script to use a simple filter:

#     if (hitFace/hitVert >= 0){ ... }

# to control the potential script flow quite well.  You could also check against "gotHit".

#        outVertex is not a part of MFnMesh.closestIntersection's standard output, but closest
# face is. For this reason, we don't even bother to compute the nearest vertex unless we
# have intersected and have a good face to start from.

#     Currently this cries a lot if you have "echo all commands" on in the script editor
# until you actually plug a mesh into it - not sure why.  Remember, I'm new to this.

#        There is some slight updating weirdness when "return to source = yes".  Not sure why.
# It seems that it needs to fail twice to actually return if it had just succeeded.