CS39440-Major-Project

Teaching aid for water colour painting

The goal of this application is to assist a new watercolour painter with producing their first painting.

This software is a free alternative to prohibatively expensive painting tools which are not aimed at teaching a beginner-level audience the basics of watercolour paintings.

Installation and Running the Code

All dependencies for the project can be installed by running:

pip install - r requirements.txt

Then, to run the application:

python3 main.py

To run the tests:

python3 - m pytest  ./tests/ -s

Content

The purpose of this application is to help a new watercolour painter to produce their first painting.

To do this, the application provides the following features:

• Upload your Chosen Image - Firstly, to use the application, you need to select the image you would like help with painting. Clicking the 'Open' button and selecting the image will open it in the center of the screen. Opening an image will unlock all the image processing functions. If your chosen image is too large, a new version will be automatically created with a unique filename and saved to the 'Downloads' directory of your computer, without modifying your original image. This ensures the application runs without performance issues whilst maintaining your original image.

• Viewing a Line Drawing - Typically, the first step in any watercolour painting is a line drawing in pencil of the scene you wish to paint. Clicking 'View Line Drawing' after opening an image will show you what your image will look like as a line drawing.

• Viewing a Value Study: There are two types of value study included in this application:

  • View and Modify Greyscale Value Layers - Clicking the 'Greyscale Value Layers' dropdown and selecting an option allows you to modify the intensity of each individual greyscale value in the greyscale version of the image. This can help you to understand the borders of these colours and modify their appearance in your final painting to suit your tastes. For each greyscale colour in the image, there is a slider you can adjust. You can increase or decrease the number of total sliders by clicking the up or down arrows on the spinbox labelled "Total Greyscale Layers" to a maximum of eight or a minimum of two. You can also adjust the blur slider to recreate the 'squinting' effect which can help us view the general shapes in the image.

  • Modifiy Greyscale Boundaries - you can change the boundaries between where the shadows, midtones and highlights begin by clicking on the 'Value Boundary Layers' dropdown and selecting one of the options. Layer one has just one slider, where you can adjust the shadows. With two, you can adjust the shadows and mid - tones and with three you can adjust shadows, mid - tones and highlights. There is similarly the ability to adjust the blur slider to recreate the 'squint' effect which can help us view the general shapes in the image.

• Making a Colour Swatch - You can view a swatch of the colours in your chosen image by clicking on the "Colour Swatch Layers" dropdown and selecting one of the options. Each corresponding number to the swatch refers to the reduced palette in the image, so for example 'Colour Swatch 3' shows a reduced palette with three colours and thus a swatch of three colours. The reduced palette and swatch count can be increased to a maximum of twelve or decreased to a minimum of two by clicking the up or down arrows respectively on the spinbox labelled "Total Colour Swatch Layers". The blur slider can be adjusted to recreate the 'squint' effect which can help us view the general shapes in the image.

• Viewing Common Paint Colours on the Colour Wheel - From any colour swatch view, you can click 'View Paint Colours' to view the five most common colour pigments and the three most common earth tones' location on the colour wheel.

• The Dictionary - The dictionary exists to provide definitions of some common painting terminology that you may encounter during your painting journey. The dictionary can be accessed via the 'Dictionary' button on the main window, and with the dictionary you can:

  • Add to the Dictionary - At any time, you can add a new item to the dictionary by clicking 'Add New Entry' and fill in the new term and definition in the pop up box. This will be saved in persistent storage.
  • Remove from the Dictionary - you can also remove any term from the dictionary by clicking on the item you want to remove and then the 'Delete Selected Entry' button. This will delete the item from persistent storage.
  • Find an Entry in the Dictionary - In the bar labelled 'Search for Term', you can type in a term you want to search for, and if it exists, it will appear and all other terms will be temporarily hidden.

• Saving Output - You can save the current visable image on-screen by clicking on 'Save'. These will be saved onto your computer for later viewing as a 'PNG'. The default saving location is the 'Downloads' directory. If a 2x2 grid of images is currently being displayed, these images will be merged into a single 'PNG' output.

• Help Menu - From the main window, the 'Help' button can be pressed in order to access instructions about each feature of the application. This includes a step-by-step guide on the usage of all the features discussed above and includes helpful screenshots.

Structure

The app is structured in the 'flat' layout as set out by Python Packaging User Guide. This is because the 'flat' layout does not require the maintainence of an editable installation or for the project to be installed in order to run.

The files in the app are organized into relevant folders:

• datasource contains files relating to persistent data storage. This is used for the 'Dictionary' window.

• file_io pertains to the input and output (I/O). These functions can open a user's selected image and save a new image to the user's computer.

• image_processing contains all files which accept an image and return a processed variant.

• resources contains all the icon files used in the app. Attribution for these icons can be found below in the section 'Attribution'.

• tests contains all test files, within their own subdirectories for each type of test. ui_test contains all pytest_qt UI tests, the unit folder contains all unit tests, which in practicality are just those tests relating to the database as they are the only tests that can be performed independantly of the user interface. There is also a test_images folder with images used for these tests, as the image processing functions require an image on which to operate. Attribution for these images can be found below in the section 'Attrubution'. There is also a pytest.ini file, which contains configuration information for pytest such as the version of pyqt being used or the path where the tests can be found.

• ui contains all user interface code which includes the layouts of every window and custom widgets. There is also a subdirectory, html which contains the images, CSS and HTML for the help screen, which is a HTML document being rendered locally using PyQt6-WebEngine.

• Some significant files are not inside a directory: main.py which is responsible for launching the app and terminology.sqlite which is the SQL file generated by sqlitedict inside the datasource directory.

Attribution

• Icons are taken from Google Fonts: https://fonts.google.com/icons and used under the Apache License 2.0
• Testing images included in tests/test_images are by Melanie Andersen and Ilya Shishikhin on Unsplash. Free to use under the unsplash license, which permits usage for both commercial and non commercial projects.