Contribution Guide

Contributions are welcome! Feel free to add new features, unit tests, documentation, examples, bug fixes, or even just a suggestion. However please follow the following guidelines to ensure a smooth contribution process.

Submission

  • To report a bug, submit an issue on GitHub issues. Please include as much information as possible including your operating system, python version, and steps required to reproduce the issue. If possible, attach the file you are using with the viewer as well.

  • To suggest new features or functionality changes please submit an issue on GitHub issues.

  • To submit new features or changes to the code please submit a pull request on GitHub to the main branch from your forked repository. Submissions will be automatically tested and then manually reviewed to ensure backwards compatibility with the current GUI.

Testing

  • If you are adding new features to the GUI please write unit tests for your feature. You may refer to the existing test suite for examples on how to write them.

  • Unit tests ensure that any future changes to the GUI won’t break your code making them crucial to maintaining this project long term.

  • When writing unit tests, check only that the expected user input results in the correct final behavior. Tests that look too deep into how the code itself works are vulnerable to failing over small changes even if the code overall is working correctly.

  • Please test your feature from a user’s perspective as you are developing it. There should be no way for the app to crash while it’s in use. If there is a way for a user to do something incorrectly, (for example entering an invalid file name), handle that case and alert the user via nccut.functions.alert().

Documentation

  • If you are adding a new feature please add instructions as to how to use your tool to the the documentation.

  • To update the documentation edit the reStructuredText files in the docs source folder.

  • Your code should be well documented with docstrings according to the Google python style guide. The docstrings are used to create the Python API section of the docs, so please ensure they are properly formatted.

Code Style

  • Please follow PEP-8 standards as much as possible, though readability and consistency are paramount. Two exceptions are standards E402 and E501. Please keep code line length less than or equal to 120 characters.

Tips for Adding a New Tool

  • Refer to the Kivy documentation. The Kivy python library is the backbone for all UI related aspects of this app, therefore knowing how it works and how to use it is essential for making any additions or changes.

  • Read through the Python API. This will give you an understanding of the widget tree structure and then you can use the code for the Inline Chain and Orthogonal Chain tools as examples for how to structure your tool to work with the GUI.

    • In summary, the Homescreen object serves as the root. The root creates the FileDisplay object with the correct image to display. The FileDisplay object then manages setting changes and the tools. The tools are added as children of the FileDisplay object. The tools add a Plot button to the sidebar which calls for a PlotPopup object which allows the user to view and save their data.

  • To add a button for your tool in the sidebar edit the nccut.kv file and follow the example of the current tools.

  • You should pass a reference to the home screen to your tool class upon creation. The home screen is the root of the widget tree, so doing this will allow you to access the rest of the widget tree.

  • The home screen has a reference to the active nccut.filedisplay.FileDisplay() object. This is what holds the loaded image and tools when they are created. You should add your tools as children to this object via the nccut.filedisplay.FileDisplay.tool_btn() method.

  • You can access the loaded data as well as the user selected configurations in the nccut.filedisplay.FileDisplay.config() attribute.

  • You should have a font_adapt(self, font) method which accepts a font and updates the font you use anytime there is text involved in your tool. Otherwise when the user changes the size of the window the font size of your tool will not update with the rest of the widgets.

  • When a tool is created, buttons for a Drag Mode and an Edit Mode are added to the sidebar. Your tool should have a drag mode. When drag mode is selected, clicking on the image should only move the image around, not perform any action with the tool. Your tool should have a change_dragging() method to pause anything your tool is doing as well as a dragging boolean attribute to indicate whether or not it is in dragging mode. Calling the method again should unpause your tool

  • Editing mode will also put the app in dragging mode, however editing mode will additionally add buttons “Delete Last Chain and Delete Last Point to the sidebar. If these don’t make sense with your tool you can choose to not add an edit button by editing the nccut.filedisplay.FileDisplay.tool_btn() method. Otherwise your tool must have a del_chain() and del_point() method.

  • If you’d like to create a plotting popup menu for your tool’s output data you can either edit the nccut.plotpopup.PlotPopup() code to work with your data or use nccut.plotpopup.PlotPopup() as an example and create a new popup class for your tool.