ubc-mds / imageprocessor

DSCI 524: Collaborative Software Development

ImageProcessor

Overview

Images form a significant part of the data in today's world. Whether you want to enhance your poorly-lit profile picture or analyze satellite images, filters are your best friends. In scientific image processing, at most times, the images cannot be used directly and need to be processed to extract information from them. ImageProcessor aims to make the image processing task easy and intuitive. With ImageProcessor, users can rotate the image, convert it to greyscale, flip it horizontally in black and white, and add padding to it (frame).

Python ecosystem

Our package fits in the Python ecosystem. There are plenty of packages with image and idvanced image proccessing functionalities. One of the most comprehensive image processing library in Python is scikit-image. We're looking to simply some of the images proccessing features. Moreover, we're planning to add some of the image processing functions from DSCI 511, lab3 and DSCI 572 into the package for use by MDS instructors in the future.

Functions

• flipping: This function can be used to flip the image horizontally in black and white

• greyscale: The greyscale function converts a color image into a greyscale image.

• padding: This function can be used to add padding to the the borders of an image.

• rotate: The rotate function rotates an image by the specified number of degrees.

Installation

$ pip install -i https://test.pypi.org/simple/imageprocessor

Dependencies

• Numpy, matplotlib, skimage

Usage

from imageprocessor.flipping import flipping

from imageprocessor.greyscale import greyscale

from imageprocessor.padding import padding

from imageprocessor.rotate import rotate

1. flipping(input_path, output_path)

Arguments:
- input_path: path to input image
- output_path: path to output image

2. greyscale(input_path, output_path)

Arguments:
- input_path: path to input image
- output_path: path to output image

3. padding(input_path, width, output_path)

Arguments:
- input_path: path to input image
- width: number of pixels of padding to be added
- output_path: path to output image

4. rotate(input_path, degrees, output_path)

Arguments:
- input_path: path to input image
- degrees: the degrees to rotate the image by
- output_path: path to output image

Documentation

The official documentation is hosted on Read the Docs: https://imageprocessor.readthedocs.io/en/latest/

Contributors

We welcome all contributions to this project! If you notice a bug, or have a feature request, please open up an issue here. If you'd like to contribute a feature or bug fix, you can fork our repo and submit a pull request. We will review pull requests within 7 days. All contributors must abide by our code of conduct.

Credits

This package was created with Cookiecutter and the UBC-MDS/cookiecutter-ubc-mds project template, modified from the pyOpenSci/cookiecutter-pyopensci project template and the audreyr/cookiecutter-pypackage.

imageprocessor's Issues

Finish Markdown files

CONTRIBUTORS.md  (Once the projects have been created, edit CONTRIBUTORS.md to add the contributor names (the students on the teams).)
CONDUCT.md
CONTRIBUTING.md
README.md 

Function #2: Grayscale

The function should be written defensively. That is, it should handle incorrect input and errors detected during execution via throwing exceptions with useful error messages, and there should be tests to confirm that the exceptions result in the expected behaviour of the function.

refer to #9 (comment)

Function specifications

For this milestone you will write function documentation that will serve as specifications, but you will NOT write any code for your package functions. Specifically, set-up empty functions (with appropriate function names) containing no code in the files where you will eventually write code. Write function documentation (e.g., complete docstrings). These are the functions you wrote about in your proposal.

License Discussion

After examining the other license options for our project. We decided to stay with our original choice MIT license.

We believe our license is appropriate for the following reasons:

• MIT license is a very commonly used license which means most people already know about it.
• We believe the MIT license, as a widely used practice, has covered most of the copyright rules for the project.
• The license is also designed for open-source package development, which will help us to waive some liabilities.
• The license is business-friendly and open-source-friendly while still allowing for monetization.
• The license will help us protect the copyright of our code and prevent potential lawsuits.

New ideas or Test cases

If you think of new ideas or test cases and you do not have time to implement them in this milestone, create an issue for them which you can complete during the next milestone.

Documentation

Your package documentation should be very clear by the end of this milestone and deployed by ReadTheDocs. All docstrings for all functions should be rendered using the napolean Sphinx extnesion and readable on ReadTheDocs. Your documentation should also include a demonstration of how to use each function in the package, so that any user with minimal Python expertise would be able to run your package functions and play around with them

GitHub actions workflow for continuous deployment

Your task here is to make sure the workflow in .github/workflows/deploy.yml is correctly configured so it runs the test suite, style checkers and deplys to package to test PyPI on pushes to your project’s repository’s deployment branch (typically the main branch). At time of submission, we expect that your project successfully runs this workflow. This should be evidenced by a green release button on your package repository’s README.

A couple things you might need to change in your .github/workflows/deploy.yml file:

1. Ensure the deployment branch (typically the main branch) is correctly specified on lines 7
2. Ensure that the correct Python version is listed on line 14 (it should match the version in your pyproject.toml file)

Specific expectation milestone 1

You should be committing to git every time you work on this project. The git commit messages should be meaningful. These will be marked. It is OK if one or two are less meaningful, but most should be.

In this project, we ask you to follow the GitHub Flow workflow. In particular, once the repositories are set up, each team member will

create a branch

work on the function you are responsible for in this branch

add commits

open a pull request

wait for the code review and feedback from another team member, and once you have addressed the feedback from the other team member(s), one of them will merge your pull request

Use GitHub for project-related communication.

Use GitHub issues to communicate with team mates (as opposed to email or Slack).

Create project boards using GitHub and link tasks to issues.

Create GitHub milestones to group related issues. In particular, make a milestone for this milestone called milestone1 and put all the relevant issues linked to it.

Use proper grammar and full sentences throughout the project, especially in your README.

Submission for Milestone 2

Function #4 Padding

The function should be written defensively. That is, it should handle incorrect input and errors detected during execution via throwing exceptions with useful error messages, and there should be tests to confirm that the exceptions result in the expected behaviour of the function.

refer to #11 (comment)

Create project structure for the Python project

• Create project structure for python project and push it as a public repository in the UBC-MDS organization on Github.com.

• The name of the repositories should be relevant to the package/project topics.

• During project creation, you will be prompted to pick a license and for now choose the MIT license. You may change it later when you learn more about licenses.

• Once the projects have been created, edit CONTRIBUTORS.md to add the contributor names (the students on the teams).

• Edit CONDUCT.md to include the code of conduct for contributing to your project. The intention behind creating this file is fostering a healthy and positive work dynamic. Recall that you already have done something similar in DSCI 522, and you can start with that document and adapt it for your new team. Note that when you create the project structure with the methods above, a default version of this file will be created. You may choose to use it or adapt it with appropriate attributions.

• Agree upon a collaboration strategy that describes how you will work together on this project (e.g., GitHub flow and edit CONTRIBUTING.md to reflect your strategy. Again, there will be a default version of this file. You can use it as is or adapt it with appropriate attribution. Here are some example CONTRIBUTING.md files for your reference.

• Software Carpentry CONTRIBUTING.md

• Outline the package you would like to build in the README.md file. (This can be identical for both projects at this point in the project). In particular, your README.md should contain:

• a summary paragraph that describes the project at a high level

• a bulleted list of the functions (and datasets if applicable) that will be included in the package (this should be a 1-2 sentence description for each function/dataset)

• a paragraph describing where your packages fit into the Python ecosystem (are there any other Python packages that have the same/similar functionality? Provide links to any that do. If none exist, then clearly state this as well).

Function #1: Flipping

The function should be written defensively. That is, it should handle incorrect input and errors detected during execution via throwing exceptions with useful error messages, and there should be tests to confirm that the exceptions result in the expected behaviour of the function.

refer to #8 (comment)

Submission

In the textbox provided on Canvas for the Milestone 1 assignment you must include:

The URL of your public project’s repo

The URL to a release on your project repo named v0.1.0

A link to your team work document that is accessible to the teaching team. Alternatively a copy of your team work document can be pasted there.

Software Licence

Describes how you will permit others to use your work

Pick a topic

Come up with a topic for your project. Discuss the topic with your TA or lab instructor and proceed only after your topic has been approved by one of them.

Function #3: Rotation

The function should be written defensively. That is, it should handle incorrect input and errors detected during execution via throwing exceptions with useful error messages, and there should be tests to confirm that the exceptions result in the expected behaviour of the function.

refer to #10 (comment)

GitHub actions workflow for continuous integration

Your task here is to make sure the workflow in .github/workflows/build.yml is correctly configured so that at a minimum, it runs the test suite and style checkers on pushes and pull requests to your project’s repository’s deployment branch (typically the main branch). At time of submission, we expect that your project successfully runs this workflow.

A couple things you might need to change in your .github/workflows/build.yml file:

1. Ensure the deployment branch (typically the main branch) is correctly specified on lines 7 & 10
2. Ensure that the correct Python version is listed on lines 21 and 24 (it should match the version in your pyproject.toml file)

Manage issues

Manage issues effectively through project boards and milestones, make it clear who is responsible for what and what project milestone each task is associated with. In particular, create an issue for each function in the package. Each of these issues must be assigned to a single person on the team. We want all of you to get coding experience in the project and each team member should be responsible for a function in R and Python. So if you are a team of four, you’ll be writing four functions for each package and if you are a team of three, you will be writing three functions for each package.

Team Contract

Similar to what you did in DSCI 522, create a team-work contract. The contract should outline how you are committed to work together so that you are accountable to one another. Again, you may start with your team contract document from 522 and adapt it for your new team. It is a fairly personal document and please do not push it into your public repositories. Instead, save it somewhere your team can easily share it, and you can share a link to it, or a copy with us in your submission to Canvas to prove you did this.

URL shared on Slack

Submission

The URL for each of your your public projects’ repositories

The URL to a release for each of your projects’ repositories

Branches

For creating branches, we are naming our branch name by our name for easier identification.
E.g: pygram-joshua