Merge pull request #56 from indranilsinharoy/packaging

Changes made for PyPI packaging

.gitignore

@@ -39,6 +39,11 @@ local.properties
 .spyderworkspace
 .spyderproject
 
+#################
+## PyCharm
+#################
+.idea/
+
 ###############################
 ## Visual Studio/ PTVS projects
 ###############################

Doc/index.html

@@ -0,0 +1,30 @@
+<h1 id="pyzdde-python-zemax-dde-extension">PyZDDE: Python Zemax DDE Extension</h1>
+<h2 id="installing">Installing</h2>
+<p>To install <strong>PyZDDE</strong> use a command prompt and <code>cd</code> to the extracted folder. Then execute</p>
+<pre class="sourceCode python"><code class="sourceCode python">python setup.py install</code></pre>
+<h2 id="things-to-do-after-installation">Things to do after installation</h2>
+<h3 id="initial-setup">Initial setup</h3>
+<ol style="list-style-type: decimal">
+<li><strong>PUSH LENS PERMISSION:</strong> All operations through the DDE affect the lens in the DDE server (except for array ray tracing). In order to copy the lens from the DDE server to the Zemax application /LDE, you need to &quot;push&quot; the lens from the server to the LDE. To do so, please enable the option &quot;Allow Extensions to Push Lenses&quot;, under File-&gt;Preferences-&gt;Editors tab.</li>
+<li><strong>ANSI/UNICODE TEXT ENCODING:</strong> PyZDDE supports both ANSI and UNICODE text from Zemax. Please set the appropriate text encoding in PyZDDE by calling module function pyz.setTextEncoding(text_encoding) (assuming that PyZDDE was imported as import pyzdde.zdde as pyz). By default, UNICODE text encoding is set in PyZDDE. You can check the current text encoding by calling pyz.getTextEncoding() function. Please note that you need to do this only when you change the text setting in Zemax and not for every session.</li>
+<li><strong>PURE NSC MODE:</strong> (This is more of a note) If want to work on an optical design in pure NSC mode, please start ZEMAX in pure NSC mode before initiating the communication with PyZDDE. There is no way to switch the ZEMAX mode using external interfaces.</li>
+</ol>
+<h3 id="zpl-macros-files-supplied-with-pyzdde">ZPL macros files supplied with PyZDDE</h3>
+<p>PyZDDE comes with few ZPL macro files that are present in the directory &quot;ZPLMacros&quot;. They are occasionally used by PyZDDE (for example in the function <code>ipzCaptureWindowLQ()</code>). Please copy/move the files from the folder &quot;ZPLMacros&quot; to the folder where Zemax/ Optic studio expects to find ZPL macros (By default, this folder is <code>C:\&lt;username&gt;\Documents\ZEMAX\Macros</code>). A copy of the &quot;ZPLMacros&quot; folder is always available in (installed with) the PyZDDE package.</p>
+<h3 id="examples">Examples</h3>
+<p>Examples shipped with PyZDDE are in the folder &quot;Examples&quot;. Please move the examples to your desired location after extracting the PyZDDE package.</p>
+<h2 id="usage">Usage</h2>
+<p>Start Zemax/ OpticStudio, import PyZDDE in a script/ IPython notebook, create a DDE communication channel, control/ communicate/ ray-trace, etc in Zemax, and close the link. For example, the following is a simple <code>Hello world</code> program.</p>
+<pre class="sourceCode python"><code class="sourceCode python"><span class="ch">import</span> pyzdde.zdde <span class="ch">as</span> pyz
+ln = pyz.createLink()
+<span class="dt">print</span>(<span class="st">&quot;Hello Zemax version: &quot;</span>, ln.zGetVersion())
+ln.close()</code></pre>
+<h2 id="modules-in-pyzdde">Modules in PyZDDE</h2>
+<ul>
+<li><strong>zdde</strong> (<code>import pyzdde.zdde as pyz</code>): The main module in PyZDDE that provides all dataitems related functions for interacting with Zemax/OpticStudio using the DDE interface.</li>
+<li><strong>arraytrace</strong> (<code>import pyzdde.arraytrace as at</code>): provides functions for tracing large number of rays</li>
+<li><strong>zfileutils</strong> (<code>import pyzdde.zfileutils as zfu</code>): provides helper functions for various Zemax file handling operations such as reading and writing beam files, .ZRD files, creating .DAT and .GRD files for grid phase /grid sag surfaces, etc.</li>
+<li><strong>systems</strong> (<code>import pyzdde.systems as osys</code>): provides helper functions for quickly creating basic optical systems.</li>
+</ul>
+<h2 id="getting-started-usage-and-other-documentation">Getting started, usage, and other documentation</h2>
+<p>Getting started with PyZDDE is really very simple as shown in the &quot;Hello world&quot; program above. Please refer to the [GitHub wiki page](<a href="https://github.com/indranilsinharoy/PyZDDE/wiki" class="uri">https://github.com/indranilsinharoy/PyZDDE/wiki</a>). It has detailed guide on how to start using PyZDDE. The wiki also has various other documentation on several topics. Please refer to the GitHub wiki documentation. Also, examples included with PyZDDE are viewable [here](<a href="http://nbviewer.ipython.org/github/indranilsinharoy/PyZDDE/tree/master/Examples/" class="uri">http://nbviewer.ipython.org/github/indranilsinharoy/PyZDDE/tree/master/Examples/</a>).</p>

Doc/index.rst

@@ -0,0 +1,62 @@
+PyZDDE: Python Zemax DDE Extension
+==================================
+
+Installing
+----------
+
+To install **PyZDDE** use a command prompt and ``cd`` to the extracted folder. Then execute 
+
+.. code:: python
+  
+     python setup.py install
+
+
+Things to do after installation
+-------------------------------
+
+
+Initial setup
+~~~~~~~~~~~~~
+
+1. **PUSH LENS PERMISSION:** All operations through the DDE affect the lens in the DDE server (except for array ray tracing). In order to copy the lens from the DDE server to the Zemax application /LDE, you need to "push" the lens from the server to the LDE. To do so, please enable the option "Allow Extensions to Push Lenses", under File->Preferences->Editors tab.
+2. **ANSI/UNICODE TEXT ENCODING:** PyZDDE supports both ANSI and UNICODE text from Zemax. Please set the appropriate text encoding in PyZDDE by calling module function `pyz.setTextEncoding(text_encoding)` (assuming that PyZDDE was imported as `import pyzdde.zdde as pyz`). By default, UNICODE text encoding is set in PyZDDE. You can check the current text encoding by calling `pyz.getTextEncoding()` function. Please note that you need to do this only when you change the text setting in Zemax and not for every session.
+3. **PURE NSC MODE:** (This is more of a note) If want to work on an optical design in pure NSC mode, please start ZEMAX in pure NSC mode before initiating the communication with PyZDDE. There is no way to switch the ZEMAX mode using external interfaces.
+
+ZPL macros files supplied with PyZDDE
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PyZDDE comes with few ZPL macro files that are present in the directory "ZPLMacros". They are occasionally used by PyZDDE (for example in the function ``ipzCaptureWindowLQ()``). Please copy/move the files from the folder "ZPLMacros" to the folder where Zemax/ Optic studio expects to find ZPL macros (By default, this folder is ``C:\<username>\Documents\ZEMAX\Macros``). A copy of the "ZPLMacros" folder is always available in (installed with) the PyZDDE package.
+
+
+Examples
+~~~~~~~~
+
+Examples shipped with PyZDDE are in the folder "Examples". Please move the examples to your desired location after extracting the PyZDDE package. 
+
+
+Usage
+-----
+
+Start Zemax/ OpticStudio, import PyZDDE in a script/ IPython notebook, create a DDE communication channel, control/ communicate/ ray-trace, etc in Zemax, and close the link. For example, the following is a simple ``Hello world`` program.
+
+.. code:: python
+
+    import pyzdde.zdde as pyz
+    ln = pyz.createLink()
+    print("Hello Zemax version: ", ln.zGetVersion())
+    ln.close()
+
+
+Modules in PyZDDE
+-----------------
+
+-  **zdde** (``import pyzdde.zdde as pyz``): The main module in PyZDDE that provides all dataitems related functions for interacting with Zemax/OpticStudio using the DDE interface.
+-  **arraytrace** (``import pyzdde.arraytrace as at``): provides functions for tracing large number of rays
+-  **zfileutils** (``import pyzdde.zfileutils as zfu``): provides helper functions for various Zemax file handling operations such as reading and writing beam files, .ZRD files, creating .DAT and .GRD files for grid phase /grid sag surfaces, etc.
+-  **systems** (``import pyzdde.systems as osys``): provides helper functions for quickly creating basic optical systems.
+
+
+Getting started, usage, and other documentation
+-----------------------------------------------
+
+Getting started with PyZDDE is really very simple as shown in the "Hello world" program above. Please refer to the [GitHub wiki page](https://github.com/indranilsinharoy/PyZDDE/wiki). It has detailed guide on how to start using PyZDDE. The wiki also has various other documentation on several topics. Please refer to the GitHub wiki documentation. Also, examples included with PyZDDE are viewable [here](http://nbviewer.ipython.org/github/indranilsinharoy/PyZDDE/tree/master/Examples/).

Examples/Scripts/arrayTraceSimple.py

@@ -22,16 +22,12 @@
 
 if sys.version_info[0] > 2:
     xrange = range
-
-# The ZEMAX file path
 cd = os.path.dirname(os.path.realpath(__file__))
-ind = cd.find('Examples')
-pDir = cd[0:ind-1]
-zmxfile = 'Cooke 40 degree field.zmx'
-filename = os.path.join(pDir, 'ZMXFILES', zmxfile)
 
 def trace_rays():
     ln = pyz.createLink()
+    filename = os.path.join(ln.zGetPath()[1], 'Sequential', 'Objectives', 
+                            'Cooke 40 degree field.zmx')
     ln.zLoadFile(filename)
     print("Loaded zemax file:", ln.zGetFile())
     ln.zGetUpdate()   # In general this should be done ...
@@ -81,6 +77,7 @@ def trace_rays():
                                     rd[k].Eyi, rd[k].Ezr, rd[k].Ezi, rd[k].intensity))
                     f.write(line)
         print("Success")
+        print("Ray trace data outputted to the file {}".format(outputfile))
     else:
         print("There was some problem in ray tracing")
 

Examples/Scripts/blankFile.py

@@ -12,18 +12,7 @@
 #              is pretty stable.  
 #-------------------------------------------------------------------------------
 from __future__ import print_function
-import sys
 import traceback
-
-#****************** Add PyZDDE to Python search path **************************
-
-PyZDDEPath = 'C:\PyZDDE'  # Assuming PyZDDE unzipped here; if not, change the path 
-                          # appropriately
-
-if PyZDDEPath not in sys.path:
-    sys.path.append(PyZDDEPath)
-#******************************************************************************
-
 import pyzdde.zdde as pyz
 
 # Create a DDE link object

Examples/Scripts/concentricSpheres.py

@@ -176,10 +176,10 @@ def spot_radius_map(nFields= 15, N=51, EE=80, zoom=10, bsavefig=False):
 
 if __name__ == '__main__':
     cd = os.path.dirname(os.path.realpath(__file__))
-    ind = cd.find('Examples')
+    ind = cd.find('Examples')  
     pDir = cd[0:ind-1]
     zmxfile = 'ConcentricSpheres.zmx'
-    filename = os.path.join(pDir, 'ZMXFILES', zmxfile)
+    filename = os.path.join(pDir, 'ZMXFILES', zmxfile) # Change the filename appropriately 
     ln = pyz.createLink() 
     ln.zLoadFile(filename)
     ln.zPushLens() # push lens to the LDE as array tracing only works with the file in the LDE

Examples/Scripts/plotSpiralSpot.py

@@ -9,25 +9,13 @@
 # Licence:   MIT License
 #-------------------------------------------------------------------------------
 from __future__ import print_function
-import sys
 import os
 import matplotlib.pyplot as plt
-
-# *********** Add PyZDDE to the python search path ***********************
-cd = os.path.dirname(os.path.realpath(__file__))
-ind = cd.find('Examples')
-pDir = cd[0:ind-1]
-##
-if pDir not in sys.path:
-    sys.path.append(pDir)
-# ************************************************************************
 import pyzdde.zdde as pyz
 
-# The ZEMAX file path
-zmxfile = 'Cooke 40 degree field.zmx'
-filename = os.path.join(pDir, 'ZMXFILES', zmxfile)
-
 ln = pyz.createLink()
+filename = os.path.join(ln.zGetPath()[1], 'Sequential', 'Objectives', 
+                        'Cooke 40 degree field.zmx')
 # Load a lens file into the ZEMAX DDE server
 ln.zLoadFile(filename)
 hx = 0.0

Examples/Scripts/plotSpiralSpotUsingArrayTrace.py

@@ -53,7 +53,7 @@ def trace_zSpiralSpot(ln, hx=0.0, hy=0.4, waveNum=1, spirals=10, numRays=600):
     x, y, z, _ = ln.zSpiralSpot(hx, hy, waveNum=waveNum, spirals=spirals, 
                                 rays=numRays)
     endTime = time.clock()
-    print("Execution time = {:4.2f}".format((endTime - startTime)*10e3), "ms")
+    print("Execution time (zSpiralSpot) = {:4.2f}".format((endTime - startTime)*10e3), "ms")
     plotTracedData(x, y)
 
 
@@ -83,7 +83,7 @@ def spiralSpot_using_zArrayTrace(hx=0.0, hy=0.4, waveNum=1, spirals=10, numRays=
             x[i-1] = rd[i].x
             y[i-1] = rd[i].y
         endTime = time.clock()
-        print("Execution time = {:4.2f}".format((endTime - startTime)*10e3), "ms")
+        print("Execution time (zArrayTrace) = {:4.2f}".format((endTime - startTime)*10e3), "ms")
         plotTracedData(x, y)
     else:
         print("Error in tracing rays")
@@ -104,21 +104,18 @@ def spiralSpot_using_zGetTraceArray(hx=0.0, hy=0.4, waveNum=1, spirals=10, numRa
     # parse traced data and plot 
     err, _, x, y, _, _, _, _, _, _, _, _, _ = tData
     endTime = time.clock()
-    print("Execution time = {:4.2f}".format((endTime - startTime)*10e3), "ms")
+    print("Execution time (zGetTraceArray) = {:4.2f}".format((endTime - startTime)*10e3), "ms")
     if sum(err)==0:
         plotTracedData(x, y)
     else:
         print("Error in tracing rays")
 
 
 if __name__=='__main__':
-    # specify the zmx file to use
-    zmxfile = 'Cooke 40 degree field.zmx'
-    cDir = ospath.dirname(ospath.realpath(__file__))
-    ind = cDir.find('Examples')
-    pDir = cDir[0:ind-1]
-    filename = ospath.join(pDir, 'ZMXFILES', zmxfile)
+    # Create link and load Zemax file
     ln = pyz.createLink()
+    filename = ospath.join(ln.zGetPath()[1], 'Sequential', 'Objectives', 
+                           'Cooke 40 degree field.zmx')
     # Load a lens file into the Zemax DDE server
     ln.zLoadFile(filename)
     SPIRALS, RAYS = 100, 6000

MANIFEST.in

@@ -0,0 +1,16 @@
+include LICENSE.txt
+include README.rst
+include MANIFEST.in
+include Notice.txt
+recursive-include Doc *.rst *.html
+include pyzdde/emfplus.exe
+include pyzdde/convert.exe
+include pyzdde/settings.ini-dist
+recursive-include pyzdde/arraytrace *.dll *h *c
+recursive-include Examples/Scripts *.py *.zbf *.png *.txt *.CFG
+recursive-include Examples/Misc *.py 
+recursive-include Examples/IPNotebooks *.ipynb
+recursive-include ZPLMacros *.ZPL
+recursive-include ZMXFILES *.ZMX *.zmx *.SES *.CFG *.txt
+prune Test
+prune Examples/IPNotebooks/.ipynb_checkpoints