|
| 1 | +Questions & Answers |
| 2 | +=================== |
| 3 | + |
| 4 | +Here are some questions you may have about the details of how to use puzzlepiece. |
| 5 | +If the topics below don't answer your question, consider submitting an issue at |
| 6 | +https://github.com/jdranczewski/puzzlepiece/issues and I will try to reply! |
| 7 | + |
| 8 | +Can I use puzzlepiece as a generic GUI framework? |
| 9 | ++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 10 | +Absolutely! It was created with experiment automation in mind, but the param/action |
| 11 | +abstractions are widely applicable, and I've been using puzzlepiece to rapidly |
| 12 | +create GUI tools for all sorts of things. |
| 13 | + |
| 14 | +Why puzzlepiece? |
| 15 | +++++++++++++++++ |
| 16 | +A number of other experiment automation frameworks exists of course. puzzlepiece was |
| 17 | +born from a desire for a solution that makes the GUI a core priority, while still |
| 18 | +providing a unified, convenient API for accessing hardware through code. |
| 19 | + |
| 20 | +I think the balance I've landed on is pretty good, and it does technically allow |
| 21 | +you to use puzzlepiece as the GUI frontend to other automation frameworks. |
| 22 | + |
| 23 | +Here are some features that I count as the core ideas of puzzlepiece: |
| 24 | + |
| 25 | +* Pre-made widgets allow for rapid GUI prototyping, while giving you a unified API |
| 26 | + "for free". |
| 27 | +* Effortless modularity - you can divide your problem into many Pieces, and they can |
| 28 | + easily communicate with each other through the Puzzle. If parts of your problem |
| 29 | + change, add new Pieces or sub-class the existing ones! |
| 30 | +* Quick and easy to set up with Jupyter Notebooks, which is incredibly powerful both |
| 31 | + for development and use - align your experiment using the GUI, but define measurements |
| 32 | + in code for example. |
| 33 | +* Useful beyond the lab. I've been using puzzlepiece whenever I need to create a GUI |
| 34 | + tool. I find it's the quickest way to throw together Qt apps, or modules that can |
| 35 | + all talk to each other. |
| 36 | +* Not very opinionated - the core abstraction of puzzlepiece (Pieces with params and |
| 37 | + actions) is meant to be flexible - you design your app and how it should work, we |
| 38 | + provide and standardise the parts that would be tedious to write manually. |
| 39 | +* Good for beginners once set up. Many experiments require people who would prefer not |
| 40 | + to have to touch Python to operate them. You can create neat GUIs for them! And for |
| 41 | + the next steps, the ``get_value``/``set_value`` paradigm is an intuitive way to |
| 42 | + interact with hardware and makes for easier coding. |
| 43 | + |
| 44 | +How does puzzlepiece talk to experimental hardware? |
| 45 | ++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 46 | +Puzzlepiece itself doesn't! The goal of this library is to provide you with a |
| 47 | +universal abstraction layer that makes building a GUI and automating its operation |
| 48 | +easier, standardised, and modular. |
| 49 | +This is achieved through the concepts of params and actions giving you premade |
| 50 | +GUI components that are simple to create, and together build a universal API that |
| 51 | +makes talking to your setup consistent. |
| 52 | + |
| 53 | +The hardware communication is something you need to implement yourself by |
| 54 | +creating setters and getters for the various params. For example, ThorLabs provides |
| 55 | +a Python API for their ThorCam cameras. You need to identify the parameters you'd |
| 56 | +like to expose through puzzlepiece (checkbox for connection, spinbox for integration time, |
| 57 | +array param for the camera image, ...) and create getters and setters for these params yourself. |
| 58 | + |
| 59 | +Once that is done for the various bits of equipment you have, you can access your whole |
| 60 | +setup through the same, modular interface! So there's some upfront time investment, but that's |
| 61 | +generally true for creating any GUI/hardware interface, and after that in my experience |
| 62 | +using your setup is much more smooth. |
| 63 | + |
| 64 | +Should I use threads? |
| 65 | ++++++++++++++++++++++ |
| 66 | +You can! But think carefully about where and how exactly these should be used. Most things |
| 67 | +in puzzlepiece are single-threaded *on purpose*, so that we can guarantee an execution order |
| 68 | +for the function calls you make. Set the moving stage, then adjust the projected image, and then |
| 69 | +take a picture with the camera - no race conditions, just sequential execution. This means |
| 70 | +the GUI will freeze during some actions, but this can be considered a feature - something |
| 71 | +is happening, and so we will wait for it to finish before doing anything else or told |
| 72 | +explicitly to refresh. This way you have a high degree of control over how things happen. |
| 73 | + |
| 74 | +If you *do* want to update the GUI during a main thread process, call |
| 75 | +:func:`puzzlepiece.puzzle.Puzzle.process_events` - this will return control to the GUI loop |
| 76 | +for a bit, so plots can be drawn, button presses and keybord shortcuts processed. This can |
| 77 | +be good, as it allows for live-ish updates, and stopping the process using the stop button, |
| 78 | +but introduces a little bit of unpredictability - what if the user changes something? |
| 79 | + |
| 80 | +For things that are not critical to run sequentially and which benefit from not freezing |
| 81 | +the GUI, have a look at :mod:`puzzlepiece.threads` - for example, |
| 82 | +:class:`puzzlepiece.threads.PuzzleTimer` is a Widget that lets you run an action repeatedly |
| 83 | +in a background thread (like get an image from a camera for a live preview), and |
| 84 | +:class:`puzzlepiece.threads.Worker` is a nice abstration for putting more generic tasks in |
| 85 | +threads. |
| 86 | + |
| 87 | +The :func:`puzzlepiece.param.BaseParam.get_value` and :func:`puzzlepiece.param.BaseParam.set_value` |
| 88 | +methods are thread-safe by default, so can be used to safely update the GUI (progress bar for |
| 89 | +example) from a Worker thread. Have a look at :class:`puzzlepiece.threads.Worker` |
| 90 | +for a more detailed discussion of this. |
| 91 | + |
| 92 | +You can also control-click on the buttons in the GUI (or press control+enter) to set/get values |
| 93 | +in a thread, though do that at your own risk - if you press get twice for example during a camera |
| 94 | +exposure, the manufacturer's API may get confused. This is best used for independent things - say |
| 95 | +you want to keep the camera running while you set the position of a moving stage. |
0 commit comments