We are now ready to decide what exactly we want our pinhole software to do.

In our case allowing for the decimal point/comma would offer a false sense of precision: There is little if any noticeable difference between the focus lengths of 50 and 51 , so allowing the user to input something like 50.5 is not a good idea. This is my opinion, mind you, but I am the one writing this program. You can make other choices in yours, of course.

Finally, we need to decide whether to allow the use of the decimal point (in which case we must also consider the fact that much of the world uses a decimal comma ).

In our case, we also need to decide what units the input should come in: We choose millimeters because that is how most photographers measure the focus length.

Secondly, I like the # character to denote the start of a comment which extends to the end of the line. This does not take too much effort to code, and lets me treat input files for my software as executable scripts.

There is no reason for the computer to spit out a number of complaints:

What is the best pinhole diameter for the focal length of 150?

Plus, it allows me to break up the monotony of computing and type in a query instead of just a number:

Personally, I like to keep it simple. Something either is a number, so I process it. Or it is not a number, so I discard it. I don’t like the computer complaining about me typing in an extra character when it is obvious that it is an extra character. Duh!

We need to decide what delimiters to accept: Do the input numbers have to be separated by a comma? If so, how do we treat two numbers separated by something else?

When it encounters the first comma, it must know it is no longer receiving the digits of the first number. It must be able to convert the digits of the first number into the value of 100 . And the digits of the second number into the value of 150 . And, of course, the digits of the third number into the numeric value of 210 .

Our program needs to consider more than a single byte of input at a time. When it sees the first 1 , it must understand it is seeing the first digit of a decimal number. When it sees the 0 and the other 0 , it must know it is seeing more digits of the same number.

For example, if we want the program to calculate the pinhole diameter (and other values we will discuss later) at the focal lengths of 100 mm , 150 mm , and 210 mm , we may want to enter something like this:

But our pinhole program cannot just work with individual characters, it has to deal with larger syntactic units.

One program, ftuc used the state machine to consider at most two input bytes at a time.

Most of the programs we have written so far worked with individual characters, or bytes, as their input: The hex program converted individual bytes into a hexadecimal number, the csv program either let a character through, or deleted it, or changed it to a different character, etc.

Since its main purpose is to help us design a working pinhole camera, we will use the focal length as the input to the program. This is something we can determine without software: Proper focal length is determined by the size of the film and by the need to shoot “regular” pictures, wide angle pictures, or telephoto pictures.

Secondly, many users will just want to go with either Bender’s constant or Connors’ constant. To make it easier on them, we will interpret -b as identical to -p04 , and -c as identical to -p037 .

In other words, if the user wants 0.04 , we will expect him to type -p04 , or set PINHOLE=04 in his environment. So, if he says -p9999999 , we will interpret it as 0.9999999 —still ridiculous but at least safer.

Or, we just may make it impossible for the user to enter a huge number. This is the approach we will take: We will use an implied 0. prefix.

Or, we might say, “Tough! The user should know better."”

Or, we may spend more time on the program so it can handle huge numbers. We might do that if we were writing commercial software for computer illiterate audience.

It may crash the program because we have not designed it to handle huge numbers.

Allowing that is actually a security risk. The PC constant is a very small number. Naturally, we will test our software using various small values of PC . But what will happen if someone runs the program choosing a huge value?

At first site, it seems obvious to use the PINHOLE=0.04 format for the environment variable, and -p0.04 for the command line.

We also need to decide what format our PC option should have.

Otherwise , if it finds a permanent option (e.g., an environment variable), it should accept it, and ignore the default.

If it finds an ad hoc choice (e.g., command line parameter), it should accept that choice. It must ignore any permanent choice and any default.

Given this system, the program may find conflicting options, and handle them this way:

Finally, a program always needs a default . The user may not make any choices. Perhaps he does not know what to choose. Perhaps he is “just browsing.” Preferably, the default will be the value most users would choose anyway. That way they do not need to choose. Or, rather, they can choose the default without an additional effort.

This type of choice is usually done with command line parameters.

The other way allows us to make ad hoc decisions: “Though I usually want you to use 0.039, this time I want 0.03872.” In other words, it allows us to override the permanent choice.

Because we only need to choose one such parameter, we will go with the second method and search the environment for a variable named PINHOLE .

Usually, a program uses one or the other of the above methods. Otherwise, if a configuration file said one thing, but an environment variable another, the program might get confused (or just too complicated).

The configuration file is used mostly by programs that have many configurable parameters. Those that have only one (or a few) often use a different method: They expect to find the parameter in an environment variable . In our case, we might look at an environment variable named PINHOLE .

The permanent choices may be stored in a configuration file, typically found in the user’s home directory. The file usually has the same name as the application but is started with a dot. Often “rc” is added to the file name. So, ours could be ~/.pinhole or ~/.pinholerc . (The ~/ means current user’s home directory.)

One is to allow a (relatively) permanent choice that applies automatically each time the software is run without us having to tell it over and over what we want it to do.

It is traditional in Unix programming to have two main ways of choosing program parameters, plus to have a default for the time the user does not make a choice.

The most important thing we need to know when building a pinhole camera is the diameter of the pinhole. Since we want to shoot sharp images, we will use the above formula to calculate the pinhole diameter from focal length. As experts are offering several different values for the PC constant, we will need to have the choice.

12.3.3. The Output

We need to decide what we want our software to send to the output, and in what format.

Since our input allows for an unspecified number of focal length entries, it makes sense to use a traditional database–style output of showing the result of the calculation for each focal length on a separate line, while separating all values on one line by a tab character.

Optionally, we should also allow the user to specify the use of the CSV format we have studied earlier. In this case, we will print out a line of comma–separated names describing each field of every line, then show our results as before, but substituting a comma for the tab .

We need a command line option for the CSV format. We cannot use -c because that already means use Connors’ constant. For some strange reason, many web sites refer to CSV files as “Excel spreadsheet” (though the CSV format predates Excel). We will, therefore, use the -e switch to inform our software we want the output in the CSV format.

We will start each line of the output with the focal length. This may sound repetitious at first, especially in the interactive mode: The user types in the focal length, and we are repeating it.

But the user can type several focal lengths on one line. The input can also come in from a file or from the output of another program. In that case the user does not see the input at all.

By the same token, the output can go to a file which we will want to examine later, or it could go to the printer, or become the input of another program.

So, it makes perfect sense to start each line with the focal length as entered by the user.

No, wait! Not as entered by the user. What if the user types in something like this:

00000000150

Clearly, we need to strip those leading zeros.

So, we might consider reading the user input as is, converting it to binary inside the FPU , and printing it out from there.

But...

What if the user types something like this:

17459765723452353453534535353530530534563507309676764423

Ha! The packed decimal FPU format lets us input 18 –digit numbers. But the user has entered more than 18 digits. How do we handle that?

Well, we could modify our code to read the first 18 digits, enter it to the FPU , then read more, multiply what we already have on the TOS by 10 raised to the number of additional digits, then add to it.

Yes, we could do that. But in this program it would be ridiculous (in a different one it may be just the thing to do): Even the circumference of the Earth expressed in millimeters only takes 11 digits. Clearly, we cannot build a camera that large (not yet, anyway).

So, if the user enters such a huge number, he is either bored, or testing us, or trying to break into the system, or playing games—doing anything but designing a pinhole camera.

What will we do?

We will slap him in the face, in a manner of speaking:

17459765723452353453534535353530530534563507309676764423 ??? ??? ??? ??? ???

To achieve that, we will simply ignore any leading zeros. Once we find a non–zero digit, we will initialize a counter to 0 and start taking three steps:

Send the digit to the output. Append the digit to a buffer we will use later to produce the packed decimal we can send to the FPU . Increase the counter.

Now, while we are taking these three steps, we also need to watch out for one of two conditions:

If the counter grows above 18 , we stop appending to the buffer. We continue reading the digits and sending them to the output.

If, or rather when, the next input character is not a digit, we are done inputting for now. Incidentally, we can simply discard the non–digit, unless it is a # , which we must return to the input stream. It starts a comment, so we must see it after we are done producing output and start looking for more input.

That still leaves one possibility uncovered: If all the user enters is a zero (or several zeros), we will never find a non–zero to display.

We can determine this has happened whenever our counter stays at 0 . In that case we need to send 0 to the output, and perform another “slap in the face”:

0 ??? ??? ??? ??? ???

Once we have displayed the focal length and determined it is valid (greater than 0 but not exceeding 18 digits), we can calculate the pinhole diameter.

It is not by coincidence that pinhole contains the word pin. Indeed, many a pinhole literally is a pin hole, a hole carefully punched with the tip of a pin.

That is because a typical pinhole is very small. Our formula gets the result in millimeters. We will multiply it by 1000 , so we can output the result in microns.

At this point we have yet another trap to face: Too much precision.

Yes, the FPU was designed for high precision mathematics. But we are not dealing with high precision mathematics. We are dealing with physics (optics, specifically).

Suppose we want to convert a truck into a pinhole camera (we would not be the first ones to do that!). Suppose its box is 12 meters long, so we have the focal length of 12000 . Well, using Bender’s constant, it gives us square root of 12000 multiplied by 0.04 , which is 4.381780460 millimeters, or 4381.780460 microns.

Put either way, the result is absurdly precise. Our truck is not exactly 12000 millimeters long. We did not measure its length with such a precision, so stating we need a pinhole with the diameter of 4.381780460 millimeters is, well, deceiving. 4.4 millimeters would do just fine.

N.B.: I “only” used ten digits in the above example. Imagine the absurdity of going for all 18 !

We need to limit the number of significant digits of our result. One way of doing it is by using an integer representing microns. So, our truck would need a pinhole with the diameter of 4382 microns. Looking at that number, we still decide that 4400 microns, or 4.4 millimeters is close enough.

Additionally, we can decide that no matter how big a result we get, we only want to display four siginificant digits (or any other number of them, of course). Alas, the FPU does not offer rounding to a specific number of digits (after all, it does not view the numbers as decimal but as binary).

We, therefore, must devise an algorithm to reduce the number of significant digits.

Here is mine (I think it is awkward—if you know a better one, please, let me know):

Initialize a counter to 0 . While the number is greater than or equal to 10000 , divide it by 10 and increase the counter. Output the result. While the counter is greater than 0 , output 0 and decrease the counter.

N.B.: The 10000 is only good if you want four significant digits. For any other number of significant digits, replace 10000 with 10 raised to the number of significant digits.

We will, then, output the pinhole diameter in microns, rounded off to four significant digits.

At this point, we know the focal length and the pinhole diameter. That means we have enough information to also calculate the f–number.

We will display the f–number, rounded to four significant digits. Chances are the f–number will tell us very little. To make it more meaningful, we can find the nearest normalized f–number, i.e., the nearest power of the square root of 2 .

We do that by multiplying the actual f–number by itself, which, of course, will give us its square . We will then calculate its base– 2 logarithm, which is much easier to do than calculating the base–square–root–of– 2 logarithm! We will round the result to the nearest integer. Next, we will raise 2 to the result. Actually, the FPU gives us a good shortcut to do that: We can use the fscale op code to “scale” 1 , which is analogous to shift ing an integer left. Finally, we calculate the square root of it all, and we have the nearest normalized f–number.

If all that sounds overwhelming—or too much work, perhaps—it may become much clearer if you see the code. It takes 9 op codes altogether:

fmul st0, st0 fld1 fld st1 fyl2x frndint fld1 fscale fsqrt fstp st1

The first line, fmul st0, st0 , squares the contents of the TOS (top of the stack, same as st , called st0 by nasm ). The fld1 pushes 1 on the TOS .

The next line, fld st1 , pushes the square back to the TOS . At this point the square is both in st and st(2) (it will become clear why we leave a second copy on the stack in a moment). st(1) contains 1 .

Next, fyl2x calculates base– 2 logarithm of st multiplied by st(1) . That is why we placed 1 on st(1) before.

At this point, st contains the logarithm we have just calculated, st(1) contains the square of the actual f–number we saved for later.

frndint rounds the TOS to the nearest integer. fld1 pushes a 1 . fscale shifts the 1 we have on the TOS by the value in st(1) , effectively raising 2 to st(1) .

Finally, fsqrt calculates the square root of the result, i.e., the nearest normalized f–number.

We now have the nearest normalized f–number on the TOS , the base– 2 logarithm rounded to the nearest integer in st(1) , and the square of the actual f–number in st(2) . We are saving the value in st(2) for later.

But we do not need the contents of st(1) anymore. The last line, fstp st1 , places the contents of st to st(1) , and pops. As a result, what was st(1) is now st , what was st(2) is now st(1) , etc. The new st contains the normalized f–number. The new st(1) contains the square of the actual f–number we have stored there for posterity.

At this point, we are ready to output the normalized f–number. Because it is normalized, we will not round it off to four significant digits, but will send it out in its full precision.

The normalized f-number is useful as long as it is reasonably small and can be found on our light meter. Otherwise we need a different method of determining proper exposure.

Earlier we have figured out the formula of calculating proper exposure at an arbitrary f–number from that measured at a different f–number.

Every light meter I have ever seen can determine proper exposure at f 5 . 6 . We will, therefore, calculate an “f 5 . 6 multiplier,” i.e., by how much we need to multiply the exposure measured at f 5 . 6 to determine the proper exposure for our pinhole camera.

From the above formula we know this factor can be calculated by dividing our f–number (the actual one, not the normalized one) by 5.6 , and squaring the result.

Mathematically, dividing the square of our f–number by the square of 5.6 will give us the same result.

Computationally, we do not want to square two numbers when we can only square one. So, the first solution seems better at first.

But...

5.6 is a constant. We do not have to have our FPU waste precious cycles. We can just tell it to divide the square of the f–number by whatever 5.6² equals to. Or we can divide the f–number by 5.6 , and then square the result. The two ways now seem equal.

But, they are not!

Having studied the principles of photography above, we remember that the 5.6 is actually square root of 2 raised to the fifth power. An irrational number. The square of this number is exactly 32 .

Not only is 32 an integer, it is a power of 2 . We do not need to divide the square of the f–number by 32 . We only need to use fscale to shift it right by five positions. In the FPU lingo it means we will fscale it with st(1) equal to -5 . That is much faster than a division.

So, now it has become clear why we have saved the square of the f–number on the top of the FPU stack. The calculation of the f 5 . 6 multiplier is the easiest calculation of this entire program! We will output it rounded to four significant digits.

There is one more useful number we can calculate: The number of stops our f–number is from f 5 . 6 . This may help us if our f–number is just outside the range of our light meter, but we have a shutter which lets us set various speeds, and this shutter uses stops.

Say, our f–number is 5 stops from f 5 . 6 , and the light meter says we should use 1 / 1000 sec. Then we can set our shutter speed to 1 / 1000 first, then move the dial by 5 stops.