Image browser

Project goal

The goal of this project is to develop an image browser. Given a directory, display each picture in the directory as well as in its subdirectories. The learning objectives in the project include: getting familiar with OpenCV, read and display an image, interact with a display window, and perform affine transforms on the image.

Project description

This project involves creating an image browser. You will develop a simple Graphical User Interface (GUI) for browsing images which are stored in a hierarchically-structured directory tree. Let us call the top-level directory as dirA. This directory will contain some images as well as other (sub)directories. Let us call these (sub)directories as dirA1, dirA2, and so on. Each of these subdirectories in turn will contain some images and may contain other (sub)directories. This (sub)directory structure may extend to an arbitrary number of levels. Your GUI should provide the following functions:

Enable browsing of images which are stored in a hierarchically structured directory tree.
In addition to displaying images, your GUI should also display meta-data associated with the images. Available meta-data may include image file name, file path, image file type, image size (number of rows and columns), number of pixels (number of rows \(\times\) number of columns), and image file size in bytes.
Navigate to display next or previous image depending on user input.
Ensure that the image fits within specified pixel dimensions while preserving aspect ratio.

Running/testing the solution

Your solution will be invoked using the following command:

browser -h

browser -r numrows -c numcols dir

where browser – name of your executable; numrows – maximum number of rows in the display window (default: 720); numcols – maximum number of columns in the display window (default: 1080); and dir – input directory.

When invoked with -h option, it should display help similar to the following:

Image Browser v1.0
Usage: browser [params] directory        

--? , -h, --help, --usage (value:true)
    print this message                      
--c         , --cols (value:1280)
    Max number of columns on screen             
--r         , --rows (value:720)
    Max number of rows on screen                    

directory        (value:<none>)
    Directory that contains the pictures to browse

The parameters prefixed with the - (dash) are optional. You are free to use long parameter names such as --rows for -r.

Suggested implementation steps

Parse the command line. You can create your own parser or use the class CommandLineParser provided by OpenCV. Each of the optional arguments may have a default value. If the user specifies the option -h, print a help message and exit. Otherwise, assign the number of rows and number of columns from user inputs or default values. If you are running on Windows, you can find the maximum screen size and use that as default.
Open the specified directory and traverse it in depth-first order, building a vector of all files contained therein. Each element in the vector is a string specifiying the path of the file relative to your working directory. At this point, you do not know whether these files contain an image. Use the following methods to build the vector:
- Apple/Linux Use the dirent functions to open and read the directory entries. However, the function to check for directory in Linux (comparing the field d_type to DT_DIR) is finicky. It depends on the underlying file system and is know to work with ext3 or ext4 but is not guaranteed to work with other file systems. Therefore, I recommend that you use lstat to get metadata on file and use the macro S_ISDIR to determine if the file is a directory.
- Windows Download the file dirent.h and use the standard functions to open and read directory entries. You can use the comparison of d_type field to DT_DIR to determine if the file is a directory.
For each file in your vector of files, read the file contents as an image (using cv::imread). If it is an image, display it and wait for user response. If it is not an image, delete the entry from your vector and move on to the next entry. The valid inputs from user are: space bar or n (for next image), p (for previous image), and q (to stop the program). Display the image information (name, size) in the console window.
Most of the images produced by the current generation of digital cameras are too big to fit onscreen. For example, a 22 megapixel camera produces an image of size \(5760 \times 3840\) pixels while a large screen is barely \(1920 \times 1080\) pixels. Your screen may be smaller and the default display window dimensions are also small. So, you want to make sure that the image completely fits in the display window. You can achieve that by using the affine transformation function of OpenCV that will preserve the aspect ratio.
Be sure catch any exceptions thrown by OpenCV functions. They will help to save you a lot of trouble.

You are free to use your own methods to solve the problem. For example, you can use X11 library functions to determine the window resolution in Linux or Apple computers. Be aware of the fact that the person compiling your code may not have proper header files on her machine. You are also free to device your own mechanism to build a structure for all the files, instead of a vector of strings as suggested.

The GUI interface should respond to the following keys when the focus is on image display window:

space or n: display next image
p: display previous image
q: quit the program

Reflecting on the learning experience and teamwork

Reflect on your solution to the problem and the learning experience through this project. Trust building, connectedness, and psychological safety are the foundational elements of teamwork. Reflect on the team dynamic experienced in this project.

Team member contribution/effort assessment

Use the following rubric to rate yourself and your teams members on a scale of 1 to 5 about their individual contribution to the project (a rating of 1 being poor and 5 being outstanding). Also, please provide rationale for each rating.

	Self-assessment		Assess team member 1		Assess team member 2


Responsibilities/ Performance	Rating	Rationale	Rating	Rationale	Rating	Rationale

Attended classes and group meetings
Initiated communication and interaction with group members
Contributed and committed to the group project
Provided comments and feedback in group work
Demonstrated a positive attitude towards to the project
Any other comments

Rubric for self-assessment and grading

Use the following rubric for self-assessment and peer grading. Also, the instructor will use the same rubric for grading the project. The final grade for the project will be based on scores from the self-assessment, peer-grading and instructor grading.

	Good	Fair	Poor


Conformance to Specifications (40 points)	The program works correctly and meets all of the specifications. (40 points).	The program works correctly but implements less than 50% of the specifications. (30 points)	The program produces incorrect results or does not compile. (10 points)
Data Structures and Algorithms (20 points)	Appropriate and efficient data structures and algorithms are used. (20 points)	The data structures and algorithms used get the job done but they are neither a natural fit nor efficient. (10 points)	Solution is based on brute force approach. No consideration is given to selection of suitable data structures and algorithms. (5 points)
Testing (20 points)	Coverage of test cases is comprehensive. Following information is provided for test cases: inputs, expected results, pass/fail, and remarks.(20 points)	Coverage of test cases is low. Test case documentation is incomplete. (10 points)	Cursory treatment of testing. No documentation of test cases. (5 points)
Coding (10 points)	The code is compact without sacrificing readability and understandability. (10 points)	The code is fairly compact without sacrificing readability and understandability. (5 points)	The code is brute force and unnecessarily long. (2 points)
Readability (5 points)	The code is well organized and very easy to follow. (5 points)	The code is readable only by someone who knows what it is supposed to be doing. (3 points)	The code is poorly organized and very difficult to read. (1 points)
Documentation (5 points)	The code is self-documenting and obviates the need for elaborate documentation. It is well written and clearly explains what the code is accomplishing and how. (5 points)	The documentation is simply comments embedded in the code with some simple header comments separating functions/methods. (3 points)	The documentation is simply comments embedded in the code and does not help the reader understand the code. (2 points)

Back to course home