{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Common Image3D and Field3D Functions\n",
      "-------------------------------------\n",
      "\n",
      "Now that we know the Image3D and Field3D types, we will next talk about how they interact with each other.  Many of these examples apply to Image3Ds and Field3Ds, so I will restrict the examples to Image3Ds.  First lets declare several Image3Ds.\n"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import PyCA.Core as ca\n",
      "grid = ca.GridInfo(ca.Vec3Di(10, 10, 10))\n",
      "mType = ca.MEM_DEVICE\n",
      "\n",
      "Im0 = ca.Image3D(grid, mType)\n",
      "Im1 = ca.Image3D(grid, mType)\n",
      "Im2 = ca.Image3D(grid, mType)\n",
      "Im3 = ca.Image3D(grid, mType)\n",
      "Imout = ca.Image3D(grid, mType)\n",
      "ca.SetMem(Im0, 1)\n",
      "ca.SetMem(Im1, 2)\n",
      "ca.SetMem(Im2, 3)\n",
      "ca.SetMem(Im3, 4)\n",
      "c0 = 1 #just a constant\n",
      "c1 = 2\n",
      "c2 = 3"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Binary and Unary Arithmetic Operations\n",
      "\n",
      "We do have support for the typical binary operations '+', '-', '\\*', and '\\\\', but we recommend against using them.  The reason is this: suppose we run `Imout = Im0 + Im1 + Im2 + Im3`.  This will be legal, but it will be slow and memory intensive because we need to allocate and deallocate memory (the size of each image) 3 times. Therefore, we have pre defined functions that perform most of these operations.  The typical binary operations are fairly straightforward, with the first argument being the output argument.  Note that the `C` in the function name reflects that you are performing the opeartion with a constant. (With a field, the C represents either a constant or a Vec3Df)"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ca.Add(Imout, Im0, Im1) #Imout = Im0 + Im1\n",
      "ca.Sub(Imout, Im0, Im1) #Imout = Im0 - Im1\n",
      "ca.Mul(Imout, Im0, Im1) #Imout = Im0 * Im1\n",
      "ca.Div(Imout, Im0, Im1) #Imout = Im0 / Im1\n",
      "\n",
      "ca.AddC(Imout, Im0, c0) #Imout = Im0 + c0\n",
      "ca.SubC(Imout, Im0, c0) #Imout = Im0 - c0\n",
      "ca.MulC(Imout, Im0, c0) #Imout = Im0 * c0\n",
      "ca.DivC(Imout, Im0, c0) #Imout = Im0 / c0"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "We also have in-place operations, that are named as `Oper_I`:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ca.SetMem(Imout, 1.0)\n",
      "ca.Add_I(Imout, Im0) #Imout += Im0\n",
      "ca.Sub_I(Imout, Im0) #Imout -= Im0\n",
      "ca.Mul_I(Imout, Im0) #Imout *= Im0\n",
      "ca.Div_I(Imout, Im0) #Imout /= Im0\n",
      "ca.AddC_I(Imout, c0) #Imout += c0\n",
      "ca.SubC_I(Imout, c0) #Imout -= c0\n",
      "ca.MulC_I(Imout, c0) #Imout *= c0\n",
      "ca.DivC_I(Imout, c0) #Imout /= c0"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "For the Unary operations, += maps directly to Add_I or AddC_I, so there is no performance difference in using the unary operator.  Therefore, the following commands are equivalent to the last set of commands, and in fact they are usually preferred (for clarity)."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "Imout += Im0\n",
      "Imout -= Im0\n",
      "Imout *= Im0\n",
      "Imout /= Im0\n",
      "Imout += c0\n",
      "Imout -= c0\n",
      "Imout *= c0\n",
      "Imout /= c0"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 4
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "##N-ary Arithmetic operations\n",
      "\n",
      "###Order of Operations/Function Naming\n",
      "\n",
      "For longer series of these arithmetic operations, the naming scheme for the functions fits the following order of operations\n",
      "\n",
      "- Operations to the left of a `_` are done last\n",
      "- Everything else is done in left-to-right order\n",
      "\n",
      "For example, \n",
      "\n",
      "`Add_AddMulC(Imout, Im1, Im2, Im3, c0)` is equivalent to `Imout = Im1 + (Im2 + Im3)*c0` and \n",
      "\n",
      "`Add_AddMulC_I(Imout, Im1, Im2, c0)` is equivalent to `Imout = Imout + (Im1 + Im2)*c0`\n",
      "\n",
      "Below is a comprehensive list (along with definitions) of the N-ary Arithmetic operations.  Each operation should have a corresponding in-place version."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ca.AddDiv(Imout, Im0, Im1, Im2) # Imout = (Im0+Im1)/Im2\n",
      "ca.AddMul(Imout, Im0, Im1, Im2) # Imout = (Im0+Im1)*Im2\n",
      "ca.AddMulC(Imout, Im0, Im1, c0) # Imout = (Im0+Im1)*c0\n",
      "ca.AddCMulC(Imout, Im0, c0, c1) # Imout = (Im0+c0)*c1\n",
      "ca.AddCMulCAddC(Imout, Im0, c0, c1, c2) # Imout = (Im0+c0)*c1 + c2\n",
      "ca.Add_AddMulC(Imout, Im0, Im1, Im2, c0) # Imout = Im0 + (Im1+Im2)*c0\n",
      "ca.Add_Mul(Imout, Im0, Im1, Im2) # Imout = (Im0+Im1)*Im2\n",
      "ca.Add_MulC(Imout, Im0, Im1, c0) # Imout = Im0 + Im1*c0\n",
      "ca.Add_MulMulC(Imout, Im0, Im1, Im2, c0) # Imout = Im0 + Im1*Im2*c0\n",
      "ca.Add_SubMulC(Imout, Im0, Im1, Im2, c0) # Imout = Im0 + (Im1-Im2)*c0\n",
      "ca.MulAdd(Imout, Im0, Im1, Im2) # Imout = Im0*Im1 + Im2\n",
      "ca.MulCAdd(Imout, Im0, c0, Im1) # Imout = Im0*c0 + Im1\n",
      "ca.MulCAddC(Imout, Im0, c0, c1) # Imout = Im0*c0 + c1\n",
      "ca.MulCSub(Imout, Im0, c0, Im1) # Imout = Im0*c0 - Im1\n",
      "ca.MulC_Add_MulC(Imout, Im0, c0, Im1, c1) # Imout = Im0*c0 + Im1+c1\n",
      "ca.MulMul(Imout, Im0, Im1, Im2) # Imout = Im0*Im1*Im2\n",
      "ca.MulMulC(Imout, Im0, Im1, c0) # Imout = Im0*Im1*c0\n",
      "ca.MulSub(Imout, Im0, Im1, Im2) # Imout = Im0*Im1 - Im2\n",
      "ca.SubDiv(Imout, Im0, Im1, Im2) # Imout = (Im0-Im1)/Im2\n",
      "ca.SubMul(Imout, Im0, Im1, Im2) # Imout = (Im0-Im1)*Im2\n",
      "ca.SubMulC(Imout, Im0, Im1, c0) # Imout = (Im0-Im1)*c0\n",
      "ca.Sub_AddMulC(Imout, Im0, Im1, Im2, c0) # Imout = Im0 - (Im1+Im2)*c0\n",
      "ca.Sub_Mul(Imout, Im0, Im1, Im2) # Imout = Im0 - Im1*Im2\n",
      "ca.Sub_MulMulC(Imout, Im0, Im1, Im2, c0) # Imout = Im0 - Im1*Im2*c0\n",
      "ca.Sub_SubMulC(Imout, Im0, Im1, Im2, c0) # Imout = Im0 - (Im1-Im2)*c0"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 5
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Trigonometric Operations\n",
      "\n",
      "We also have trigonometry functions, defined the same was as the C++ [cmath library](http://www.cplusplus.com/reference/cmath/). Once again, we also have corresponding in-place opeartions."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ca.Sin(Imout, Im0)\n",
      "ca.Cos(Imout, Im0)\n",
      "ca.Tan(Imout, Im0)\n",
      "ca.Cot(Imout, Im0)\n",
      "ca.Sec(Imout, Im0)\n",
      "ca.Csc(Imout, Im0)\n",
      "ca.Asin(Imout, Im0)\n",
      "ca.Acos(Imout, Im0)\n",
      "ca.Atan(Imout, Im0)\n",
      "ca.Atan2(Imout, Im0, Im1)\n",
      "ca.Atan2C(Imout, Im0, c0)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### Relational and Comparison Operators\n",
      "\n",
      "We have relational functions (==, !=, >, >=, etc.). Image3D's only hold float values (and not bools), so these operations return 1.0 for True and 0.0 for False.  As before, we have corresponding in-place operations."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ca.EQ(Imout, Im0, Im1) # Imout = (Im0 == Im1)\n",
      "ca.EQC(Imout, Im0, c0) # Imout = (Im0 == c0)\n",
      "ca.NEQ(Imout, Im0, Im1) # Imout = (Im0 != Im1)\n",
      "ca.NEQC(Imout, Im0, c0) # Imout = (Im0 != c0)\n",
      "ca.LT(Imout, Im0, Im1) # Imout = (Im0 < Im1)\n",
      "ca.LTC(Imout, Im0, c0) # Imout = (Im0 < c0)\n",
      "ca.LTE(Imout, Im0, Im1) # Imout = (Im0 <= Im1)\n",
      "ca.LTEC(Imout, Im0, c0) # Imout = (Im0 <= c0)\n",
      "ca.GT(Imout, Im0, Im1) # Imout = (Im0 > Im1)\n",
      "ca.GTC(Imout, Im0, c0) # Imout = (Im0 > c0)\n",
      "ca.GTE(Imout, Im0, Im1) # Imout = (Im0 >= Im1)\n",
      "ca.GTEC(Imout, Im0, c0) # Imout = (Im0 >= c0)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### Other Numerical Operators\n",
      "\n",
      "We also have many other operators that don't fit into the above categories.  They have in-place versions."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "ca.Abs(Imout, Im0) # Imout = |Im0|\n",
      "ca.AbsDiff(Imout, Im0, Im1) # Imout = |Im0 - Im1|\n",
      "ca.SqrDiff(Imout, Im0, Im1) # Imout = (Im0 - Im1)^2\n",
      "ca.Ramp(Imout, Im0) # Imout(x<0) = 0; Imout(x>=0) = Imout(x)\n",
      "ca.Sgn(Imout, Im0) # Imout(x<0) = -1; Imout(x>0) = Imout(1)\n",
      "ca.Step(Imout, Im0) # Imout(x<0) = 0; Imout(x>0) = Imout(1)\n",
      "\n",
      "ca.Ceil(Imout, Im0)\n",
      "ca.Floor(Imout, Im0)\n",
      "ca.Round(Imout, Im0)\n",
      "\n",
      "ca.Copy(Imout, Im0) # Imout = Im0\n",
      "ca.Neg(Imout, Im0) # Imout = -Im0\n",
      "\n",
      "ca.Sqr(Imout, Im0) # Imout = Im0^2\n",
      "ca.Cube(Imout, Im0) # Imout = Im0^3\n",
      "ca.PowC(Imout, Im0, c0) # Imout = Im0^c0\n",
      "ca.Sqrt(Imout, Im0)\n",
      "ca.Exp(Imout, Im0) # Imout = e^Im0\n",
      "ca.Log(Imout, Im0) # natural log\n",
      "\n",
      "ca.Min(Imout, Im0, Im1) # element-wise minimum\n",
      "ca.MinC(Imout, Im0, c0) # element-wise minimum with a constant\n",
      "ca.Max(Imout, Im0, Im1) # element-wise maximum\n",
      "ca.MaxC(Imout, Im0, c0) # element-wise maximum with a constant\n"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 8
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Image3D to Real Number Operations\n",
      "\n",
      "The past operations have always had an Image3D as an output, but we also have summary functions that return either a float or two floats:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print ca.Sum(Im2) # sum(Im2)\n",
      "print ca.Sum2(Im2) # sum2(Im2^2)\n",
      "print ca.Min(Im2)\n",
      "print ca.Max(Im2)\n",
      "print ca.MinMax(Im2)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "3000.0\n",
        "9000.0\n",
        "3.0\n",
        "3.0\n",
        "[3.0, 3.0]\n"
       ]
      }
     ],
     "prompt_number": 9
    }
   ],
   "metadata": {}
  }
 ]
}