root/trunk/RBRapier/RBRapier/Tools/Projections.py

#!/usr/bin/env python
##~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
##~ License 
##~ 
##- The RuneBlade Foundation library is intended to ease some 
##- aspects of writing intricate Jabber, XML, and User Interface (wxPython, etc.) 
##- applications, while providing the flexibility to modularly change the 
##- architecture. Enjoy.
##~ 
##~ Copyright (C) 2002  TechGame Networks, LLC.
##~ 
##~ This library is free software; you can redistribute it and/or
##~ modify it under the terms of the BSD style License as found in the 
##~ LICENSE file included with this distribution.
##~ 
##~ TechGame Networks, LLC can be reached at:
##~ 3578 E. Hartsel Drive #211
##~ Colorado Springs, Colorado, USA, 80920
##~
##~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#~ Imports 
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

import math
import Numeric
from Transformations import TransformPrimitive3dh

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#~ Definitions 
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class ProjectionTransform(TransformPrimitive3dh):
    """
    >>> proj = ProjectionTransform(-2, 3, 5,8, -9, -2)
    >>> proj.Width
    5.0
    >>> proj.Height
    3.0
    >>> proj.Deprojh
    7.0
    >>> proj.Center
    (0.5, 6.5, -5.5)
    >>> proj.Dimensions
    (5.0, 3.0, 7.0)
    >>> proj.HCenter
    0.5
    >>> proj.VCenter
    6.5
    >>> proj.DCenter
    -5.5
    """
    def __init__(self, left=-1.0, right=1.0, bottom=-1.0, top=1.0, near=-1.0, far=1.0):
        self.Left = float(left)
        self.Right = float(right)
        self.Bottom = float(bottom)
        self.Top = float(top)
        self.Near = float(near)
        self.Far = float(far)

    def SetCorners(self, Lower, Higher):
        self.Left, self.Bottom, self.Near = Lower
        self.Right, self.Top, self.Far = Higher

    def GetWidth(self):
        return self.Right - self.Left
    def SetWidth(self, value):
        delta = (self.Width - value) * 0.5
        self.Right -= delta
        self.Left += delta
    Width = property(GetWidth, SetWidth)
    def GetHCenter(self, mult=0.5):
        return (self.Left + self.Right) * mult
    def SetHCenter(self, value):
        hw = self.Width * 0.5
        self.Right = value + hw
        self.Left = value - hw
    HCenter = property(GetHCenter, SetHCenter)

    def GetHeight(self):
        return self.Top - self.Bottom
    def SetHeight(self, value):
        delta = (self.Height - value) * 0.5
        self.Top -= delta
        self.Bottom += delta
    Height = property(GetHeight, SetHeight)
    def GetVCenter(self, mult=0.5):
        return (self.Top + self.Bottom) * mult
    def SetVCenter(self, value):
        hw = self.Height * 0.5
        self.Top = value + hw
        self.Bottom = value - hw
    VCenter = property(GetVCenter, SetVCenter)

    def GetDeprojh(self):
        return self.Far - self.Near
    def SetDeprojh(self, value):
        delta = (self.Deprojh - value) * 0.5
        self.Far -= delta
        self.Near += delta
    Deprojh = property(GetDeprojh, SetDeprojh)
    def GetDCenter(self, mult=0.5):
        return (self.Far + self.Near) * mult
    def SetDCenter(self, value):
        hw = self.Deprojh * 0.5
        self.Far = value + hw
        self.Near = value - hw
    DCenter = property(GetDCenter, SetDCenter)

    def GetCenter(self):
        return (self.HCenter, self.VCenter, self.DCenter)
    def SetCenter(self, value):
        self.HCenter, self.VCenter, self.DCenter = value
    Center = property(GetCenter, SetCenter)
    def GetDimensions(self):
        return (self.Width, self.Height, self.Deprojh)
    def SetDimensions(self, value):
        self.Width, self.Height, self.Deprojh = value
    Dimensions = property(GetDimensions, SetDimensions)

    def GetAspectRatio(self):
        return self.Height / self.Width
    def SetAspectRatio(self, value, byWidth=None):
        self.SetDimensionsAspectRatio(self.Width, self.Height, value)
    AspectRatio = property(GetAspectRatio, SetAspectRatio)

    def SetDimensionsAspectRatio(self, width, height, aspectYX=1., largest=True):
        width, height, aspectYX = map(float, (width, height, aspectYX))
        if largest: # scale by larger dimension
            if height/width > aspectYX: # height is greater -- scale width
                width = height/aspectYX
            else: # width is greater -- scale height
                height = width*aspectYX
        else: # scale by smaller dimension
            if height/width < aspectYX: # width is greater -- scale height
                width = height/aspectYX
            else: # height is greater -- scale width
                height = width*aspectYX
        self.Width, self.Height = width, height
        return width, height

    def GetTuple(self):
        return self.Left, self.Right, self.Bottom, self.Top, self.Near, self.Far
    def SetTuple(self, value):
        self.Left, self.Right, self.Bottom, self.Top, self.Near, self.Far = value
    asTuple = property(GetTuple, SetTuple)

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class Orthographic(ProjectionTransform):
    """
    >>> proj = Orthographic(-2, 3, 5,8, -9, -2); proj
    <Orthographic: l=-2.0, r=3.0, b=5.0, t=8.0, n=-9.0, f=-2.0 >
    >>> proj.asArray4x4()
    array([[ 0.40000001,  0.        ,  0.        ,  0.2       ],
           [ 0.        ,  0.66666669,  0.        ,  4.33333349],
           [ 0.        ,  0.        , -0.2857143 , -1.57142854],
           [ 0.        ,  0.        ,  0.        ,  1.        ]],'f')
    """

    def asArray4x4(self):
        """As defined by the OpenGL Red Bock"""
        width = self.Width
        height = self.Height
        deprojh = self.Deprojh
        xoff = self.GetHCenter(1.) / width
        yoff = self.GetVCenter(1.) / height
        zoff = self.GetDCenter(1.) / deprojh

        result = Numeric.asarray([
            [2./width, 0., 0., xoff],
            [0., 2./height, 0., yoff],
            [0., 0., -2./deprojh, zoff],
            [0., 0., 0., 1.]],
            self.NumericType)
        return result

    def __repr__(self):
        return "<Orthographic: l=%s, r=%s, b=%s, t=%s, n=%s, f=%s >" % self.asTuple

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class Viewport(Orthographic):
    """
    >>> proj = Viewport(0, 10, 0, 10, -1, 1); proj
    <Viewport: l=0.0, r=10.0, b=0.0, t=10.0, n=-1.0, f=1.0 >
    >>> proj.asArray4x4()
    array([[ 5.,  0.,  0.,  5.],
           [ 0.,  5.,  0.,  5.],
           [ 0.,  0.,  1.,  0.],
           [ 0.,  0.,  0.,  1.]])
    >>> proj.asInverse4x4()
    array([[ 0.2,  0. ,  0. , -1. ],
           [ 0. ,  0.2,  0. , -1. ],
           [ 0. ,  0. ,  1. ,  0. ],
           [ 0. ,  0. ,  0. ,  1. ]])
    >>> # Create "screen" coordinates"
    >>> v = Numeric.transpose(Numeric.asarray([(4.,4.,0.,1.),(6.,6.,0.,1.)])); v
    array([[ 4.,  6.],
           [ 4.,  6.],
           [ 0.,  0.],
           [ 1.,  1.]])
    >>> # Convert to v to [-1,1] nominal coordinates
    >>> vn = Numeric.dot(proj.asInverse4x4(), v); vn
    array([[-0.2,  0.2],
           [-0.2,  0.2],
           [ 0. ,  0. ],
           [ 1. ,  1. ]])
    >>> # Convert back to "screen" coordinates
    >>> Numeric.dot(proj.asArray4x4(), vn)
    array([[ 4.,  6.],
           [ 4.,  6.],
           [ 0.,  0.],
           [ 1.,  1.]])
    """

    def __init__(self, left=0., right=1., bottom=0., top=1., near=-1., far=1.):
        self.Left = float(left)
        self.Right = float(right)
        self.Bottom = float(bottom)
        self.Top = float(top)
        self.Near = float(near)
        self.Far = float(far)

    def asArray4x4(self):
        """As defined by the OpenGL Red Bock"""
        halfwidth = 0.5 * self.Width
        halfheight = 0.5 * self.Height
        halfdeprojh = 0.5 * self.Deprojh
        xoff = self.GetHCenter()
        yoff = self.GetVCenter()
        zoff = self.GetDCenter()

        result = Numeric.asarray([
            [halfwidth, 0, 0, xoff],
            [0, halfheight, 0, yoff],
            [0, 0, halfdeprojh, zoff],
            [0, 0, 0, 1]])
        return result

    def __repr__(self):
        return "<Viewport: l=%s, r=%s, b=%s, t=%s, n=%s, f=%s >" % self.asTuple

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class Frustum(ProjectionTransform):
    """
    >>> proj = Frustum(-2, 3, 5,8, -9, -2); proj
    <Frustm: l=-2.0, r=3.0, b=5.0, t=8.0, n=-9.0, f=-2.0 >
    >>> proj.asArray4x4()
    array([[-3.5999999 ,  0.        ,  0.2       ,  0.        ],
           [ 0.        , -6.        ,  4.33333349,  0.        ],
           [ 0.        ,  0.        ,  1.57142854, -2.57142854],
           [ 0.        ,  0.        , -1.        ,  0.        ]],'f')
    """

    def __init__(self, left=-1.0, right=1.0, bottom=-1.0, top=1.0, near=1., far=10.):
        ProjectionTransform.__init__(self, left, right, bottom, top, near, far)

    def asArray4x4(self):
        """As defined by the OpenGL Red Bock"""
        width = self.Width
        height = self.Height
        deprojh = self.Deprojh
        xoff = self.GetHCenter(1.) / width
        yoff = self.GetVCenter(1.) / height
        zoff = self.GetDCenter(1.) / deprojh
        near2 = self.Near * 2.
        ugly = -self.Near * self.Far / deprojh

        result = Numeric.asarray([
            [near2/width, 0., xoff, 0.],
            [0., near2/height, yoff, 0.],
            [0., 0., -zoff, ugly],
            [0., 0., -1., 0.]],
            self.NumericType)
        return result

    def __repr__(self):
        return "<Frustm: l=%s, r=%s, b=%s, t=%s, n=%s, f=%s >" % self.asTuple

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class Perspective(Frustum):
    """
    >>> proj = Perspective(30., 1.234, 0.5, 23.2)
    >>> proj
    <Persepctive: ViewAngle=30.0, Aspect=1.234, n=0.5, f=23.2 >
    >>> proj.asArray4x4()
    array([[ 4.60535049,  0.        ,  0.        ,  0.        ],
           [ 0.        ,  3.7320509 ,  0.        ,  0.        ],
           [ 0.        ,  0.        , -1.04405284, -0.51101321],
           [ 0.        ,  0.        , -1.        ,  0.        ]],'f')
    >>> proj.AspectRatio
    1.2339999999999995
    >>> proj.ViewAngle
    30.000000000000011
    >>> proj.ViewRadians
    0.52359877559829904
    """

    def __init__(self, viewangle=45., aspectratio=1., near=1., far=10.):
        """Derived from OpenGL Red Book"""
        Frustum.__init__(self,-1.,1.,-1.,1.,near,far)
        self.SetViewAngleAndRatio(math.radians(viewangle), float(aspectratio))

    def __repr__(self):
        return "<Persepctive: ViewAngle=%s, Aspect=%s, n=%s, f=%s >" % (self.ViewAngle, self.AspectRatio, self.Near, self.Far)

    def GetViewAngle(self):
        return math.degrees(2.*math.atan(self.Height/(2.*self.Near)))
    def SetViewAngle(self, value):
        self.SetViewRadians(math.radians(value))
    ViewAngle = property(GetViewAngle, SetViewAngle)

    def GetViewRadians(self):
        return 2.*math.atan(self.Height/(2.*self.Near))
    def SetViewRadians(self, value):
        ar = self.AspectRatio
        self.SetViewAngleAndRatio(float(value), ar)
    ViewRadians = property(GetViewRadians, SetViewRadians)

    def SetViewAngleAndRatio(self, viewradians, aspectratio):
        self.Height = math.tan(0.5*viewradians) * 2. * self.Near
        self.Width = self.Height / aspectratio

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#~ Testing 
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

if __name__=='__main__':
    print "Testing..."
    import doctest, Projections
    doctest.testmod(Projections)
    print "Test complete."