-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathREADME
More file actions
118 lines (103 loc) · 8.99 KB
/
README
File metadata and controls
118 lines (103 loc) · 8.99 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
noam.kimhi,or_forshmit8
--------------------------------------------------------------------------------------------------------------
# QUESTION 1 - Description of every class in our program and the relationships between them:
Package image_char_matching:
(*) CharConverter: This class was given to us. No changes were made here.
(*) SubImgCharMatcher: This class is responsible for matching an ASCII character to a sub-image with a
given brightness. It receives an array of characters and assigns each of them a
brightness value. According to user's request, it will return a char matching the
given brightness value. This class behaves efficiently upon adding/removing chars,
and will only normalize the entire character set if the added/removed character
changes the minimum/maximum brightness value.
Package image:
(*) Image: This class was given to us. No changes were made here.
(*) ImagePadder: This is a utility class responsible for padding a given image with white borders s.t its
dimensions will be powers of 2. Since this is a utility class it has no fields, and all
of its methods are static.
Assumes the given image has an even (not odd) width and height (as stated in the exercise
description).
(*) SubImageHandler: A utility class handling the dividing of an image and calculating brightness values.
Sub-image division - Given an image and a resolution, this class is responsible for
dividing a given image to an array of square sub-images, each of them the size of
resolution².
Brightness value - Given an image, calculate its brightness value.
Package ascii_art:
(*) KeyboardInput: This class was given to us. No changes were made here.
(*) AsciiArtAlgorithm: The algorithm that runs the entire process.
This class has an efficiency mechanism that allows future runs of the algorithm to
take less time with less calls to unnecessary methods.
We are saving the following static fields and behave accordingly:
- CharacterSet: We only update the characters that were not calculated in the
previous run, using the efficient methods of SubImgCharMatcher.
- ImagePath: If the image path has not changed, there's no need to pad it again,
hence we save the previous padded image since we decided space
complexity of saving the padded image matters less than the run time
of the algorithm.
- Resolution: If the image hasn't changed but the resolution did, we can use the
padded image and only create the sub-images again.
if both the resolution and the image haven't changed,
we save the previous subImages' brightness values and only assign
each sub-image the matching ASCII character.
We decided not to save the entire Ascii-Art output between runs for cases in which
only the output method has changed (console/html) because we do not expect the
users to make these 2 consequent action - in which case it will be effective to
save the previous output. It will force our algorithm to save a large size of
arrays in order to implement it. For the same reason we decided to not save the
previous round method, because again it will require saving the previous output in
case it hasn't changed.
(*) Shell: A class that activates a shell for the user to interact with and control the algorithm's
settings. Has private fields to save the current user settings throughout the run of the shell
such as character set, desired resolution, output method etc. In order to control the output
method we used the polymorphism of AsciiOutput interface which will be determined
according to user's request.
(*) RoundMethod: enum that stores the 3 valid round methods.
Package utils:
(*) MathUtils: A utility math class that contains a math operation that was required in multiple packages
in the program.
Package exceptions: Described in Question 3.
Package ascii_output: Was given to us. No changes were made here.
Relationships between classes:
(*) SubImgCharMatcher is a part of the ASCII-art algorithm logic, after dividing a full-size picture to
sub-images by using SubImgCharMatcher we assign each of sub-image a character that represent them
according to their brightness. This method has 2 efficient methods - addChar() and removeChar() which
allows the algorithm to efficiently update the character set according to the previous run.
(*) Shell interacts with AsciiArtAlgorithm, allowing the user to change setting and run the algorithm
accordingly.
(*) ImagePadder and Shell are both using the MathUtils class in order to conduct calculation related to
image padding.
(*) RoundMethod allows both SubImgCharMatcher and AsciiArtAlgorithm to recognize the valid round methods
that were produced by the user in Shell class.
(*) CustomShellException is used by Shell class to throw exceptions that were caused by invalid user input
while using the shell.
--------------------------------------------------------------------------------------------------------------
# QUESTION 2 - Details about every Java data structure we used in our code, and the reasons behind the choice:
(*) Part 1.1 - ASCII Character set: We decided to use a HashMap to store the brightness value of each
character. The options we had were either a HashMap or a TreeMap due to the need to print
the characters in their ASCII order. However, the frequency of this operation is negligible
and will only be requested upon a user's request, while the need to get/set the brightness
value of a character will be in a greater demand throughout the ASCII-Art generating
process. A Hash-Map enables access to the brightness value of each character in constant
time (amortized). On the other hand, a TreeMap is not Hash-based, therefor accessing the
brightness values will be on O(log n) time, and will only make sorting the keys more
efficient (which as we explained, is far less important).
Space-complexity wise, a HashMap is also ideal for this situation, and will store our data
on O(n) space (where n is the number of characters). In this case there were no differences
between a TreeMap and a HashMap.
(*) Part 1.5 - Previous character set - Inside AsciiArtAlgorithm, we save the previous set of characters
in a HashSet in order to check membership in constant time (amortized) in a new run of the
algorithm if a character's brightness value was already calculated in the previous run.
In cooperation with the removeChar() and addChar() methods we have in SubImgCharMatcher
that also work efficiently (explained in Q1), this allows new runs of the algorithm to
update only the added values with minimum run-time.
--------------------------------------------------------------------------------------------------------------
# QUESTION 3 - Usage of Java Exception Mechanism in order to take care of invalid user input and printing
error messages:
We have created a dedicated package for exceptions in order to keep the project structure clean and
maintainable. Since most errors were treated the same - print a message with the same format except the
command type and the failure reason, we decided for simplicity to settle on one Exception class -
CustomShellException which extends Exception. This class formats the required message with a given
command type and failure reason. All methods that deal with user input will not directly handle the
exception, but instead throw it to the caller method in case of failure. All exceptions will be handled
inside the Shell's run() method, that prints the corresponding exception. We added another option to give
the CustomShellException the entire message, in which case it will print it (instead of formatting).
--------------------------------------------------------------------------------------------------------------