This particular tool came about as the fortunate merger of two otherwise unrelated projects that I was working on at the same time a few years back: ANSI escape codes for producing colors in the shell, and the Java Image IO library. They seemed like a natural fit together, and an ideal solution to the long-standing problem of how to view images in the shell.

So we had the pieces: ANSI escape codes, which let us basically treat characters on the terminal as though they were pixels (i.e., specify coordinates and a color), and Java Image IO, which let us easily read images of various formats and convert them into an array of pixels, ready for display. The only hard part left was mapping from (potentially) full 32-bit color images down to the 16 colors available in ANSI terminal color pallet.

The solution we went with involved the realization that unlike standard pixels, which generally take on only a single color, that “character” pixels are made up of 2 colors: the foreground, and the background. For example, a given character-pixel can be displaying a white “A” on a black background, or a bright red “#” on a yellow background. When viewed as a single pixel then, a character-pixel’s actual color value can be evaluated as the weighted average of the 2 colors being shown, with the weights being set to the number of pixels that are showing the foreground color versus those showing the background color.

For example, if a character is 7 pixels wide and 14 pixels high, that’s 98 total pixels. If displaying character “X” takes up, say, 16 of those pixels, then we would weight the foreground color (the color of the “X” pixels) at 16/98ths, and we’d weight the background color at (98-16)/98ths. So a bright red “X” (RGB=(255,85,85)) on a yellow background (RGB=(187,187,0)) would evaluate as RGB=(191,169,11), by:

fgWeight = 16/98      ~= .16
bgWeight = (98-16)/98 ~= .84
R = (fgRed  *fgWeight) + (bgRed  *bgWeight) = (255*.16) + (187*.84) ~= 191
G = (fgGreen*fgWeight) + (bgGreen*bgWeight) = (85 *.16) + (187*.84) ~= 169
B = (fgBlue *fgWeight) + (bgBlue *bgWeight) = (85 *.16) + (0  *.84) ~= 11

Using this type of calculation, we choose a handful of characters that took up a wide variety of pixels (the final set became ” “, “-”, “X”, “#”, and a special “checkerboard” char, that nicely turns on half the pixels in a character). We then build all the combinations of (foreground, background, character) triplets, which multiplies out to (16 * 16 * 5) = 1280 colors. It’s not quite True Color, but it’s like 4 times better than 256, and way better than just those 16 that ANSI gave us, right!

So now we have something like 1280 colors, in some odd distribution throughout the RGB 3-Dimensional space. The final task then is to pick a terminal-character (an FG color, BG color and a character to print) that’s the closest match to the color of a pixel in the image. Easy right? We just used the distance formula to pick which color is closest.

I think our results speak for themselves:

A few more notes:

• I have a handy image.sh in my $PATH that calls the binary distribution available below. So to view an image in my shell session, I simply execute image.sh path/to/your.image. The contents of that script tend to be as simple as java -jar path/to/javaTermGraph.jar "$1" (adjust the parameter handling, path, and shebangline all to your liking).
• This tool was developed and has always been ran using PuTTY connected to bash on Linux. In theory it might work on some other combination of platforms, but that’s up to you, as I don’t have access to any of those.
• If the image is wider than your terminal, it is scaled (using Java 2D) to your terminal’s width. Height isn’t adjusted – tall images simply scroll (probably slowly).
• I will point out that it works better with a smaller font (basically because you get more character-pixels, and/or you get character-pixels that are closer to actual pixels), so since I’m always running our hacked version of putty, I just hold control and throw my mouse wheel down to get to about a 1 or 2 pixel font.

java -jar $pathTo/javaTermGraph.jar $pathToAnImage

unzip javaTermGraph-0.1-src.zip
cd javaTermGraph-0.1-src/
ant
java -cp build com.kingsrook.termgraph.DrawImage $pathToAnImage

Until you install the extended cd function developed by kingsrook (which is available in our Downloads section).  Extended cd defines a bash function, named “cd”, meaning that it replaces the shell’s built-in cd command.  At first it might sound like a bad idea to replace the built-in cd command, but don’t worry – extended cd adds a number of great features to this most basic command, making your navigation through your system’s directory tree fast, easy, and everything you ever dreamed of (if you have very sad dreams, like me).

The first set of features in extended cd were inspired by that one trick you learned about built-in cd, which was passing an argument of “-” to switch back to the your last working directory (per environment variable $OLDPWD).  Extended cd takes it a few steps further, by introducing the argument “_” (that’s an underscore, instead of a dash).  If you run extended cd with only an underscore as it’s argument (ie, cd _), it will take you to the last directory you cd’ed into from ANY of your current or previous shell sessions on that computer.  Actually, this could extend across multiple machines, if your home directory were shared across multiple computers, as it’s based on the cd history file (which is located at ~/.cd_history), which is maintained by the extended cd function.

So why is cd _ useful?  My main use case for it would be when I first boot my PC, and I make several new PuTTY connections to a development server, and I want them all to be in the same working directory.  I only have to type/tab out that path in the first one, then in the others I can just run a cd _ to go to that same directory (the most recent entry in the cd history file).

However, that’s only the beginning of what extended cd does with the underscore argument and the cd history file.  To go a step beyond, you can add a number right after that underscore (as the same word or argument – no spaces between them), to go to the number’th most recent entry in your cd history.  For example, to go to the 2nd most recent entry in your file, you’d run cd _2.  For the third most recent, cd _3. (You may note that cd _1 would have the same effect as cd _).

You might ask, why is that useful?  For me, it’s great in the situation when you’re popping back and forth between a few different directories, that aren’t necessarily close to one another, and you don’t want to have to re-type them, or find them in your shell command history.  Or, if you know you’ve recently been in a directory, and you want to get back there, you can just start trying cd _# options, and you know you’ll quickly get back, with just a few keystrokes (i.e., try cd _2, if that’s not right, try cd _3, cd _4, cd _5, and soon enough, you’ll be there).

Now if you can’t remember when you’ve recently been in a directory, and you don’t feel like playing a guessing game to try to get there, you can use one more extended cd underscore variation, by adding a question mark after the underscore, as in:  cd _?.  When invoked like this, extended cd will print the contents of your cd history file, sorted with most recent entries last, printing the number of each entry before and after it, then will drop you at a prompt where you can enter the number of an entry to be switched directly to that directory.  If you don’t want to see your full cd history file, you can also add a number after the question mark, to only see that many entries from the file (i.e., cd _?10 to see the 10 most recent entries from the file).  Useful, eh?  Here’s a “screenshot”:

dkelkhof@king:~> cd _?10
    10  /home/dkelkhof/development/foobar_site/trunk/src/com/kingsrook/content/foobar 10
     9  /home/dkelkhof/development/foobar_site/trunk/src/com 9
     8  /home/dkelkhof/development/foobar_site/trunk/src/com/kingsrook/cgi/qdim/projects/foobar/tables/voucher 8
     7  /home/dkelkhof/development/foobar_site/trunk/src/com/kingsrook 7
     6  /home/dkelkhof/development/foobar_site/trunk/src/com/kingsrook/cgi/qdim/projects/foobar 6
     5  /home/dkelkhof/development/foobar_site/trunk 5
     4  /home/dkelkhof/development/foobar_site/trunk/src/com/kingsrook/content 4
     3  /home/dkelkhof/development/infrastructure/trunk/CRONTAB 3
     2  /home/dkelkhof/development/sas_applications/trunk/src/com/kingsrook/cgi/mcf/deployments 2
     1  /home/dkelkhof/development/webapps/trunk 1
cd> 7
dkelkhof@mlrnd02:~/development/foobar_site/trunk/src/com/kingsrook>

The next bag of tricks in extended-cd are also built on that cd history file.  This time, if you know part of a path that you have recently been to, but you don’t want to type/tab out the whole thing, you can pass it to extended cd preceded by a question mark.  For example, to get back to the utilities directory in some project you know you’ve recently worked on, you can simply run cd ?utilities. If extended cd finds one or more matches in your cd history, it prints that same menu for you, showing the matches, prompting you to enter the one you want to go back to. Beautiful.

The magic of extended cd doesn’t end there:  The next feature is great for when you’re working in a very deep directory path, and you want to go some distance up the the tree, but you don’t want to guess how many ../‘s you need to get there. What you can do in extended cd is use a third dot, followed by part of the directory name you want to end in, for example cd ...foo to move upward, however many directories are needed, until the basename of your working directory is (or contains) foo — a far shot better than cd ../../../../, then not being far enough, so doing another cd ../../../../, then going too far and having to go back down. (For reference, when working on java projects for kingsrook, I always find myself either doing cd ...ook to get back up to the top of our java packages, or cd ...src to get back to the root of our source code, or cd ...unk to get back to the root of my svn checkout).

The last feature available in extended cd mimics a shell trick I saw a college professor use once, where you can re-run your previous command after applying a basic find/replace to it, via ^find^replace. In this case, you can run cd ^foo^bar, and extended cd will take your current working path, apply the requested find/replace to it, and switch you the resulting path. This is nice if you’ve got two similar directory tress under different roots (for example, two svn working copies, let’s call them trunk and cool_branch), and you quickly want to jump from a given sub directory of one into the other (in our example, cd ^trunk^cool_branch might take you from ~/development/trunk/src/com/kingsrook/templates/site/macros/ to
~/development/cool_branch/src/com/kingsrook/templates/site/macros/ in one quick easy step).

Here’s a demo of the double-carat mode (both for general shell commands, and with extended cd):

## the shell's builtin for general commands:
dkelkhof@king:~> ls -l foo
ls: foo: No such file or directory
dkelkhof@king:~> ^foo^bar
ls -l bar
-rw-rw-r-- 1 dkelkhof group 0 2011-06-24 16:11 bar
## extended cd's version:
dkelkhof@king:~/development/trunk/src/com/kingsrook/> cd ^trunk^cool_branch
dkelkhof@king:~/development/cool_branch/src/com/kingsrook/>

So that’s it – the full feature set of extended cd. It turns that most basic, boring bash builtin into something that can truly make your development faster, more fun, and almost futuristic. Oh, it also has a -help screen, shown here, which serves as a nice remind of everything we’ve gone through here:

dkelkhof@king:~> cd -help
cd: usage: cd [-L|-P] [dir]

For extended features, use the following for [dir] (not compatible with [-L|-P] flags):
   _          - Go to last entry in cd_history.
   _number    - Go to <number>'th last entry in cd_history.
   _?         - List cd_history, prompt to select directory.
   _?number   - List last <number> cd_history entries, prompt to select directory.
   ?pattern   - Pick directory from cd_history matching <pattern>.
   .?pattern  - Pick directory from cd_history matching <pattern>, under cwd.
   ...pattern - Go up (multiple ../'s) to directory matching <pattern>.
   ^old^new   - Go to pwd, with pattern <old> replaced with <new>

wow – what?
i’ll say it again.

better is better than best

We have all heard it before.

• a bird in the hand is better than two in the bush
• there comes a time in every project when you’ve got to shoot the engineer and goto production
• 20% of 100% is 80% – and 80% is damn good

The point is, that we all too often get caught up on “more”.  We get caught up on the perfection; on the grand idea.  We can spend years getting it “just right” and in the end never do anything (think GNU Hurd).

In manufacturing, its called Lean Product Development (started by Toyota long ago).  In construction, its called “Good Enough”.  In software engineering, its called…… well – we don’t have a great name for it. it doesn’t happen enough.

The problem is with everyone – but we will start with those who enable it and encourage it.

Us; we the programmers, we the architects, we the system administrators.  We love solving problems.  We love the “Next Great Idea”.  We love the challenge.

When the project manager or the user or the customer says, “wow, this is good, but it would be great if it just had X” – instead of letting them know, that yes, we agree that X would be a “Great Thing”, but we currently have a working system that can start solving problems and saving money ready NOW and that we should go with what we have and then see what is really needed for the next step, we instead reply like a little doggy just happy to see it’s master after a long day at work. We wag our tail, try to lick their face and say “Yeppers! That would be awesome – let me go do it!”.

With each repeat of this, and it can happen at each and every step, the project slips future from the finish line.

The most amazing piece of software ever written isn’t the one the that will solve every problem and make the company wealthy beyond belief. It’s the simple program that was released 5 years ago, after a week of development and updated a little here and little there, that has been running the company and paying the bills week after week.

Linux was the “Good Enough” answer to Hurd.

There is no “Best” – there is only “Better than what we have right now”. Continue to give your customers “Better” and everything will be a “Good Thing”

Share Tweet