Programming Assignment Checklist: LFSR

Frequently Asked Questions

What are the goals of this assignment? To introduce you to object-oriented programming and to reinforce the message of Lecture 1.

Where can I review the concepts involved? Review the Lecture 1 slides to reacquaint yourself with the basic ideas behind LFSRs. Read Sections 3.1 and 3.2 of the textbook to learn the basics of object-oriented programming.

What optional files are available for this assignment?

If you want some help getting started with LFSR, we provide a template. It saves you from copying and pasting the signatures of the API. Additionally, it includes one possible choice of internal data representation (private instance variables/fields) that can be used to implement the behaviour of an LFSR. (Using different representations is allowed too.)
The template is here: LFSR.java. You are welcome to use the whole template as a starting point, or you can just peek at it when you see fit.
The archive file lfsr-pngs.zip includes a number of sample .png files including original images and encrypted versions. They are used by the examples below. You should place the .png files in the exact same directory as your .java files for this week.
You can browse the individual files in the LFSR FTP directory.

What are the APIs that I need to use as a client? How can I use them? Your code will be using Picture and Color. The back of the textbook has abbreviated APIs for them; see the Using Color and Picture section for more details.

Do the APIs that I define for LFSR and PhotoMagic need to be exactly the same as the prescribed ones? Yes, we will be testing the methods in the API directly. If your method has a different signature or does not behave as specified, you will lose a substantial number of points. You may not add public methods to the API; however, you may add private methods (which are only accessible in the class in which they are declared).

How should I represent the LFSR? There are several possible approaches. The approach outlined in the template is to use an int[] array of size N, each entry of which is either 0 or 1. If you follow this approach, the constructor amounts to creating the array and converting the char values in the string to int values for the array (and initializing your other instance variables). However, you are allowed to use any efficient representation that you like.

How do I create an instance variable which is an array if I don't know its length at compile time? Declare it as an instance variable, but initialize it in constructor (where you will know its length). For example, see Program 3.2.3 in the textbook.

What extra comments should I include when writing object-oriented programs? You must comment the purpose of every method, using the names of the argument variables in your description. Additionally, you must comment the purpose of each instance variable.

In the initial register, fill.charAt(0) is the leftmost bit. But in the Lecture 1 slides and the assignment page, bit 0 is the rightmost bit. Do I have to arrange the bits in my register array that way? Strings are always indexed from left to right (the way we read English). Traditionally, binary digits are indexed from right to left, with bit 0 as the lowest order or rightmost bit. You are welcome to use either approach here—just be careful to do it correctly and consistently.

How do I convert the char values in the string to int values for the array? The number zero is represented by the char value '0'. The char data type is a Java primitive type, so you can compare two of them with if (c == '0').

My generate() method is producing 19 for the binary number 11001. What am I doing wrong? You are calculating the bits in reverse order. 19 is the decimal value of the binary number 10011.

My generate() works with the 11 bit fill and the tap at position 8, but when I try generate()with the 20 bit fill and the tap at position 16, I get a different answer from the one shown in the example. What am I doing wrong? Make sure you are not hardwiring 11 or 8 in your LFSR code. The LFSR constructor arguments should set the size of the register and the tap position.

The toString() is not explicitly called in the test client code, but it still gets called. How does this work?

      LFSR lfsr = new LFSR("01101000010", 8);
      StdOut.println(lfsr);

Any object in Java can be promoted (converted) to String type. This is what is happening here. The way that we can tell Java how to do this promotion for an arbitrary user-defined type is by defining a .toString() method for its class. When Java wants to do a promotion, it uses the String value returned by .toString() as the converted/promoted value.

I get an ArrayOutOfBounds or NullPointerException error. What could cause this? Do your constructors initialize all of the instance variables (e.g., N, reg, and tap)? Did you allocate memory for your array with new? Did you inadvertently redeclare int N or int[] reg in a method or constructor, thereby hiding the instance variable with the same name?

How do I do exclusive or (XOR) in Java? Use the ^ Java symbol. The operation a ^ b, where a and b are int values, does a bit-by-bit exclusive or of the values. It also can be applied to boolean values.

Why I am I getting 48s and 49s when I print out values for debugging? Internally, characters are represented as integers. The code for '0' is 48, and the code for '1' is 49. (Read about ASCII or Unicode for more information.) When you perform arithmetic operations on characters, they are promoted to int. So '0' + 1 and '1' ^ '1' ^ '1' are two examples of expressions that evaluate to the int value 49. (But (char)('0'+1) is '1'.) Rather than subtracting 48s in your code, can you write your code in such a way that arithmetic is never performed directly on char values?

In .toString(), I loop the right number of times, but the returned String looks too short. What can cause this? This can be the reverse of the problem above. If you take the integer 0 or the integer 1 and cast it to a char, you end up with a special control character that looks blank when printed.

Why are we using the .png format instead of .jpg? It is a lossless format that preserves the precise bits in the colors.

How do I read in the .png files? Use the Picture data type, described in Section 3.1 of the textbook. You will only need the constructors and methods of the Picture API. To see it in action, look at the program Grayscale.java which takes the name of a picture file as a command line argument, converts all pixels to gray, and displays all those pixels. See Luminance.java to see how to retrieve the r, g, and b values for the Color.

Sometimes my encrypted picture looks like a shadowy version of the original. How do I pick a good tap number? Here are suggested tap numbers for maximizing the cycle of different size linear feedback shift registers: 5-bit (tap 2), 6-bit (tap 4), 9-bit (tap 4), 10-bit (tap 6), 11-bits (tap 8), 20-bit (tap 16), 30-bit (tap 22), 36-bit (tap 24), 48-bit (tap 42), 60 bits (tap 58), 100 bits (tap 62), and 150 bits (tap 96).

What is a java.awt.HeadlessException and how did I cause it? The assignment only asks you to call show() once, in PhotoMagic.main(). Calling it in other places can give this error.

Using Color and Picture

The Color class comes built in to Java, in the "Abstract Window Toolkit" package. Write
```
import java.awt.Color;
```
at the top of your program, then you can create Color variables such as
```
Color princetonOrange = new Color(244, 111, 27); // constructor args are R, G, B
```
There is an abbreviated API for Color on the booksite cheatsheet.
The Picture class was created for this course. Normally, Picture will already have been installed with the rest of the course materials. The import statement is not used with Picture — you can use it immediately in your code, for example
```
                          // internet connection required for this to work
Picture pic = new Picture("http://www.cs.princeton.edu/~cos126/java.png");
pic.show();               // shows Java
```
One way to check if Picture is installed is to run the following command at the command line, which calls Picture.main():
```
java-introcs Picture http://www.cs.princeton.edu/~cos126/java.png
```
If it's working correctly, you'll see an image of Java and the text output 400-by-136 at the command line.
There is an abbreviated API for Picture on the booksite cheatsheet.
If Picture does not seem to be installed correctly, one solution is to copy Picture.java to the same directory as your other files for this assignment.
Want more detail? (This is optional!) We don't recommend reading the full, technical, source code of Picture.java. (You don't need to know how a class was implemented just to use it.) Instead, read Java's automatically-built documentation pages (Javadocs). Here are the Javadoc pages for Color and Picture. Search these pages with Ctrl-F/Command-F — they have too much information for reading straight through to be useful.

Testing

Be sure to thoroughly test each piece of your code as you write it. We offer some suggestions in the assignment specification. You should also test your data type with other parameters.

Use the following code to test generate() with a 20-bit fill and a tap of 16.

LFSR lfsr; // (delete this line if lfsr is already declared!)
lfsr = new LFSR("01101000010100010000", 16);
for (int i = 0; i < 10; i++) {
    int r = lfsr.generate(8);
    StdOut.println(lfsr + " " + r);
}

It should output:

01010001000000101010 42
00000010101011011001 217
10101101100100010111 23
10010001011111000001 193
01111100000100011010 26
00010001101010011100 156
10101001110010011100 156
11001001110011100111 231
11001110011110000111 135
01111000011110111101 189

PhotoMagic. Here are a few sample executions of PhotoMagic.java along with the desired output. They require the lfsr-pngs.zip archive file mentioned above.

% java-introcs PhotoMagic pipe.png 01101000010100010000 16


% java-introcs PhotoMagic Xpipe.png 01101000010100010000 16


% java-introcs PhotoMagic Xbaboon-red.png   01101000010100010000 16

% java-introcs PhotoMagic Xbaboon-green.png 01101000010100010000 16

% java-introcs PhotoMagic Xbaboon-blue.png  01101000010100010000 16


% java-introcs PhotoMagic Xshield.png 010101010101010101010101010101 22


% java-introcs PhotoMagic Xscarpet-cookies.png 01101000010100010000 16
[ picture of something delicious ]

% java-introcs PhotoMagic Xjava.png 001110001111000100001101010010000100010010000000001100000100 58
[ picture of something you could drink with cookies ]

PhotoMagicDeluxe. Here is a sample execution of PhotoMagicDeluxe.java along with the desired output.

% java-introcs PhotoMagicDeluxe Xjava.png OPENSESAME 58
[ picture of something you could drink with cookies ]

Possible Progress Steps

These are purely suggestions for how you might make progress. You do not have to follow these steps.

Do the reading specified at the top of this page.
Read the template LFSR.java. Your program will resemble it. You will need to fill in the constructor and methods.

If you use an int[] array implementation, define the instance variables as follows:

public class LFSR {
    private int N;          // number of bits in the LFSR
    private int[] reg;      // reg[i] = ith bit of LFSR, reg[0] is rightmost bit
    private int tap;        // index of the tap bit
}

Make the constructor. Your constructor for LFSR will initialize all the instance variables. Use new to allocate memory for the int[] array. Observe that you must do this in the constructor (and not when you declare the instance variables) since otherwise you wouldn't know how big to make the array.
Write the toString() method.
As you fill in the methods for LFSR, use the test code described in the assignment.
Write the step() method. Test.
Write the generate() method. Test.
PhotoMagic. Your PhotoMagic class is a client of the Picture, Color, and LFSR classes. Place LFSR.java in the same directory as PhotoMagic.java, so the compiler will be able to find both of them. See also the section on Color and Picture.

Enrichment

Read more about Linear Feedback Shift Registers.
Look at the implementation of the Picture class.