Merge master

Author: jonathanrocher

README.md

@@ -9,11 +9,17 @@ In this workshop, we will learn to embed scientific tools into a robust
 scientific application that can scale from a tiny UI to a large platform. As an 
 example, attendees will build an image browser application (including 
 face-detection capabilities), allowing users to search through their pictures, 
-based on various criteria. We will start from a simple jupyter notebook and 
+based on various criteria. We will start from a simple python script and 
 progressively turn it into a complete application using Matplotlib and several 
 packages from the Enthought Tool Suite such as Traits, TraitsUI and Pyface. In 
 the process, attendees will learn how to design clean, maintainable and 
-scalable applications, and package them into an installer.
+scalable applications, and discuss sharing your tool with your users.
+
+Ultimately, we will be building fairly sofisticated application that allows 
+users to explore images on their machines and detect faces in them:
+
+![full app screenshot](pycasa_final.png)
+
 
 ## Set up instructions
 First step to set yourself up is to clone this repository
@@ -33,21 +39,38 @@ git clone [email protected]:jonathanrocher/ets_tutorial.git
 
 ### EDM users (recommended)
 First, download and install EDM from https://www.enthought.com/edm/. Then, 
-open a `Terminal`/`Powershell`/`Cmd Prompt`/ and navigate to the folder 
-where the repo was cloned. Enter the following command to create a 
-dedicated Python environment and install all dependencies in it:
+open a `Terminal`/`Powershell`/`Cmd Prompt`/ and create a lighweight bootstrap environment to run the installation commands.
 ```commandline
-python ci build
+edm envs create bootstrap
+edm install --environment bootstrap click
+```
+Next, enter the following commands to create a 
+dedicated Python environment called `ets_tutorial` and install all dependencies in it:
+```commandline
+edm run -e bootstrap -- python ci build --environment ets_tutorial
+```
+All application related `python` commands are assumed to run in this
+environment. You can activate the environment with:
+```commandline
+edm shell -e ets_tutorial
 ```
 
 ### Conda users
-[TODO]
+Create a new conda environment called `ets_tutorial` and install local
+dependencies with the following commands:
+```commandline
+conda create -n ets_tutorial python=3.6 pandas matplotlib traits traitsui scikit-image pillow pyqt ipython importlib_resources importlib_metadata
+conda activate ets_tutorial
+python setup.py install
+```
+Activate the new environment with `conda activate ets_tutorial`.
 
 ### pip users
 Assuming a Python environment is created and activated on your machine, for 
 example from https://www.python.org/, 
 ```commandline
 pip install pandas matplotlib traits traitsui scikits-image pillow pyqt5 ipython
+python setup.py install
 ```
 
 ## Getting help
@@ -78,37 +101,37 @@ are able to reach the end goal.
   - step 3: GUI: first traitsUI views
   - step 4: pyface application: tree navigator and double-click on an image to 
     display the traitsUI view of the image.
+  - INTERLUDE: code structure for scalability
   - step 5: Fuller pyface application: 
     - add folder editor to display a table of metadata for all images inside
     - add button to launch the face detection on all images
     - add widgets to filter images
-  - INTERLUDE: code structure for scalability
   - step 6: pyface application: adding menu and branding 
   - step 7: pyface application: advanced features [OPTIONAL]
-  - step 8: 1-click installer
+  - step 8: Packaging and sharing
 
 
 ## Contributing
-### Code structure
-[TODO]
 
 ### Rules for contributing to the repository
 Contributing to this repository requires:
-1. to make a Pull Request
-2. all code contributed must be pep8 compliant
-3. all unit tests must pass
+1. to fork the repository, branch off of master, create a branch with changes, 
+   and  make a Pull Request
+2. All code contributed must be `flake8` compliant.
+3. All unit tests must pass.
 
 
-# Instructor notes: tutorial flow
+# Tutorial flow
 
-1. Introduction 20 mins
+1. Introduction (20 mins)
     - Review development environment setup
     - Purpose and goals of the tutorial
-    - What is ETS? Why pick it to build tools? When to pick it to build tools?
+    - What is ETS? What type of products is it for?
 2. Starting script (10 min)
 3. Traits (30 mins)
-  - 
-  - Simple exercise (10 mins)
+  - Introduction to Traits: OOP with traits, trait types, and listening to 
+    changes. 
+  - Exercise (10 mins)
 4. Basic TraitsUI (35 mins) 
   - Introduction to TraitsUI views
   - The MVC paradigm

docs/ets_tutorial_prabhu.pdf

@@ -30,6 +30,8 @@ def update_editor(self):
     def _do_layout(self):
         """Creates sub-widgets and does layout.
         """
+        if not self.value:
+            return
         canvas = FigureCanvasQTAgg(figure=self.value)
         # Allow the figure canvas to expand and shrink with the main widget.
         canvas.setSizePolicy(

docs/ets_tutorial_slides.pdf

@@ -0,0 +1,187 @@
+---
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.3'
+      jupytext_version: 1.13.7
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+---
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## Sharing scientific tools: script to desktop application
+
+**Jonathan Rocher, Siddhant Wahal, Jason Chambless, Corran Webster, Prabhu Ramachandran**
+
+**SciPy 2022**
+
+<!-- #endregion -->
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## Preliminaries
+
+If you haven't already:
+- Clone the repository: https://github.com/jonathanrocher/ets_tutorial
+- Install packages:
+    - Using Enthought Deployment Manager (recommended)
+      (https://www.enthought.com/edm):
+
+       ```bash
+       edm envs create bootstrap
+       edm install --environment bootstrap click
+       edm run -e bootstrap -- python ci build --environment ets_tutorial
+       ```
+    - `ets_tutorial` will be our working Python environment. To activate:
+      ```bash
+      edm shell -e ets_tutorial
+      ```
+    - Follow instructions in README for conda and pip
+<!-- #endregion -->
+
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## Motivation
+
+- Some tasks are easier with a GUI
+- Seeing a lot of information in one shot
+- Easier for non-programmers
+- Easier to share
+
+<!-- #endregion -->
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## Why ETS? When ETS?
+
+- Open-source
+- Mature
+- Easy to start, easy to grow
+- Tools promotes reusable code and good design patterns
+- Largely declarative UI
+- Backend-agnostic: avoid having to update when PyQt, wxPython, ... update!
+- Limitless around data tools, in particular plotting!
+- Reduced development costs (single programming language)
+- No architecture mind shift necessary (client-server) and no exposure to 
+  server hacking.
+
+Limitations:
+- Limited by back-end when it comes to widgets compared to Javascript
+- Desktop application isn't a solution for all needs
+
+<!-- #endregion -->
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## What is ETS?
+
+- Enthought Tool Suite: https://docs.enthought.com/ets
+- Open Source
+- Packages
+  - Traits: Python object attributes on steroids
+  - TraitsUI: Easy GUI-building
+  - PyFace: Low-level GUI components
+  - Envisage: plug-in application framework
+  - Chaco: interactive plotting library
+  - Mayavi: 3D plotting
+  - traits_futures: running tasks in parallel/background
+  - And many others...
+
+<!-- #endregion -->
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## Layered package design
+
+<center>
+<img src="images/application_layers.png" height="90%" align="center"/>
+</center>
+
+<!-- #endregion -->
+
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## Sample screenshots
+
+- Can make quite sophisticated UIs
+- Much less code
+- Easy to write
+
+<!-- #endregion -->
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## A Mayavi-based dialog
+
+<center>
+<img src="images/lorenz_ui.png" height="90%" align="center"/>
+</center>
+
+<!-- #endregion -->
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## A customized viewer
+
+<center>
+<img src="images/pysph_viewer.png" height="90%" align="center"/>
+</center>
+
+<!-- #endregion -->
+
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## Goals
+
+- Start with simple Python script
+  - Detect faces
+  - Extract Image metadata
+
+- Build a full-fledged desktop application
+  - Easy to use UI
+  - Learn a little MVC
+  - Design application to scale
+
+- Share the application with others
+
+<!-- #endregion -->
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## Result
+
+Final application we will be building in this tutorial:
+
+<img src="../pycasa_final.png" height="90%" width="90%" align="center"/>
+
+<!-- #endregion -->
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## Schedule
+
+- Step 1: Python script
+- Step 2: Using Traits.
+- Step 3: Basic GUI using TraitsUI
+- Step 4: PyFace application: tree navigator
+- Step 5: More features
+- Step 6: Menus and branding
+- Step 7: [OPTIONAL] Advanced features
+- Step 8: [OPTIONAL] Packaging and sharing
+
+
+<!-- #endregion -->
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## Basic Python script
+
+- Uses: `PIL`, `skimage`, and `matplotlib`
+- Detects faces in a given image
+- Look inside ...
+
+<!-- #endregion -->
+
+<!-- #region slideshow={"slide_type": "slide"} -->
+## Next steps
+
+- Learn more about traits
+- Build a clean model for our task with traits
+- Learn why models are useful
+
+<!-- #endregion -->