Percival Help File

NOTICE:

Percival is shareware: You are welcome to use Percival for free, forever, and to pass out free copies of it to anybody else.

The Percival software and its related documentation are provided AS IS, and without warranty of any kind. Jay Reynolds Freeman expressly disclaims all other warranties, expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.

Table of Contents:

Introduction:

Welcome to the help file for Percival, a special-purpose pixel-oriented image editor for the Apple Macintosh™. Percival was written by me, Jay Reynolds Freeman. By all means Email me about it if you wish.

Percival was named after one of my cats, "Percival", now deceased. (I regularly name programs that I write after my cats.)

"Percival" is also an annoyingly cute acronym: Pixel Editor for the Repair and Customization of Icons, when Vector Applications Lose.

Cute or not, that acronym describes Percival concisely. In a little more detail, Percival is a rather minimalist image editor that does just one specialized thing well enough that some people may find it useful: Percival allows pixel-by-pixel touch-up and minor alteration of images that are 128 by 128 pixels in size, or smaller. Images that are 128 by 128 pixels are a standard size used for Macintosh icons. Thus Macintosh developers may find occasional use for Percival.

In particular, Percival is NOT:

A full-featured image editor.
A vector-based editor of any kind: Percival has no built-in means to draw lines, curves, zig-zags, polygons, or other specialized shapes. The best it can do is make a rectangular block of pixels all be the same color.
A reincarnation of Apple's MacPaint&trade.

Percival is designed to work paw-in-glove with several applications that Apple provides with its "XCode" software package for developers, notably "Icon Composer" and "Pixie". "Icon Composer" can create icons out of many different kinds of images, though it provides no way to edit images. "Pixie" allows a magnified view of the pixels in any image, or anywhere on the Macintosh display. As I write these words, "Icon Composer" and "Pixie" are both part of the current version of XCode, which is XCode 2.4.1.

Note in particular that Percival does not actually create icon image files. The TIFF files that Percival writes are, however, suitable input for "Icon Composer", which does create icon image files.

Apple's "Preview" application is also a useful adjunct to Percival. Among the many features of "Preview" is the ability to read an image from a file that uses one image format and write that image to a file that uses a different image format. Thus in effect you can use "Preview" to change, for example, TIFF files into PNG files. As I write these words, "Preview" is bundled with OS X.

It would be possible to use Percival to create an entire icon from scratch, but anyone who does so must have way more free time than I do: Icons are almost certainly better prepared from images made with fancier software, or perhaps from images obtained with a camera. I expect Percival to be very useful for touching them up, though.

Percival has a "pour color" command that does what the "paint bucket" tool does on many other image editors. This capability may be useful for substantial modification of icons with large blocks of pixels that are all exactly the same color.

Percival is shareware: You are welcome to use Percival for free, forever, and to pass out free copies of it to anybody else. If you should at some time wish to make a shareware donation for Percival, use my PayPal&trade account or send a check by hard-copy mail to

Jay Reynolds Freeman
Post Office Box 60628
Palo Alto, CA, 94306-0628
U. S. A.

PayPal will need my EMail address:

Jay_Reynolds_Freeman@mac.com

How much to donate is your choice, and I certainly do not insist, request, or expect that you do so.

Getting Started:

System Requirements:

Percival is a stand-alone application for the Apple Macintosh&trade. It is Universal Binary&trade, and thus should run on any Macintosh with either an Intel microprocessor such as the Core Duo&trade, or one of the older PowerPC&trade microprocessors. Percival requires the Apple OS X operating system, version 10.4 or later. Its memory and disc requirements are minimal: The program occupies only a few hundred Kilobytes on disk, and can run usefully in several Megabytes of memory. (Percival uses lots of memory to save copies of the image you are working on for the "Undo" command.)

Technical Note: Percival was implemented and tested on a 2006-model Apple Macbook&trade (Macbook version 1,1 -- a flat-black model with an 13-inch diagonal screen, a 2 GHz Intel Core Duo&trade processor, and 1 GByte of memory), running Mac OS X versions no earlier than 10.4.8. It was also tested on an old G3 portable, using the PowerPC architecture, also running OS X 10.4.8. Thus there is good cause to believe that Percival is indeed a Universal Binary application, but I must in honesty advise you that I do not have a back room full of Macintoshes in hundreds of different configurations, in which to test Percival.

It is possible that Percival will run on versions of OS X that are earlier than 10.4; possibly as early as 10.2. Unfortunately, I have not tested the program with earlier versions of OS X.

Installation:

A Percival installation comprises just the "Percival" application itself -- there are no extra files. The Percival distribution may contain some extra items, including a copy of this HTML file, a "README" file, and perhaps some interesting or useful examples of icons, but all you really need is the program. (By the way, in case you obtained this help file as a separate download, the "Percival Help" menu item, in Percival's "Help" menu, will call up this file from within the program -- you don't need a separate copy.)

"Installation" is simply the act of putting the application wherever you like. Possibly it should end up in your Applications folder, but that choice is up to you.

There is nothing to register, no activation codes required, and no enhanced versions available for a price. The shareware product, "Percival", is all there is.

You are welcome to make as many backup copies of Percival as you wish, and to give free copies of it to anyone.

Security:

Most people consider it ill-advised to run an unknown application -- like Percival -- without special precautions, because it might contain code to do something malicious. If I had deliberately written a malicious program, I certainly wouldn't tell you, at least, not until it was way too late. What's more, if you are a suspicious type -- and in today's Internet and computing environment, you should be! -- there is nothing I can do or say to convince you that I have not put some ill-intended code into Percival. Actually, I suppose it might help if I told you where I live, but I myself am a suspicious type, so I am not going to do that.

Besides, my house is a mess.

It might be useful to remember that Apple's OS X operating system is based on Unix: If you have moderate Unix experience, you might know that Unix is pretty good about keeping one user from messing with other users' data. Thus you might create a special, "dummy", user account, just for testing Percival, with access to nothing other than Percival and any images you may be using. If you know how to do that, good. If not, perhaps you should seek advice from a Unix-knowledgeable and trustworthy friend. (You shouldn't rely on me to provide the details; for all you know I am a computer criminal who might deliberately tell you something that didn't work and thereby set you up for disaster.)

Furthermore, one thing I worry about -- something every software developer worries about -- is that some third party will modify my code to be malicious, or create a malicious program with the same name and appearance as mine, and produce nefarious results thereby. I have no way to avoid this problem.

Starting Percival:

Just click on the Percival icon, and away you go. The easiest way to load an image file for editing is to drag the file to the small empty square area part way up the left side of the Percival window, the one with the label, "Drag an Image File Here".

Interacting With Percival:

Percival provides one main window, one button, a color well, and a small handful of menu items. There is one other general way of interacting with Percival that may be of particular use: Percival makes considerable use of "tooltips" -- the brief text descriptions that pop up when the cursor is positioned over particular areas of the screen. You can learn something about almost any visible feature of Percival by moving the cursor over it and waiting for the tooltip to appear.

The Percival Window:

Percival has only one window, and you can only edit one image at a time.

The Magnified Image Pane:

When Percival starts running, a large square pane, set somewhat right of center, fills most of the Percival window. That pane is where a four-times-enlarged view of the image you are editing will appear. Each pixel in the original image will appear as a four-by-four square of pixels in the enlarged image. That's almost too tiny to work with, but if the big image were much larger, it wouldn't all fit on the display of some Macintoshes.

The Normal-Size Image Pane:

There is also a much smaller square pane not quite half way up the left side of the Percival window, with the label "Drag an Image File Here". That smaller pane will hold a full-size view of the image you are editing, and as the label suggests, you can load an image for editing by dragging the image file into the smaller pane. (You can also load images by commands in the File Menu.)

The Miniature Image Panes:

When you load an image, copies of it will appear in both of the panes just mentioned. Furthermore, three additional images will appear in a horizontal row just above the full-sized image. One will be half-size, one will be quarter-size, and the last one will be one-eighth size. These images allow you to get a sense of what an icon will look like when the Macintosh operating system software resizes it. The panes for the miniaturized images will not be visible until you load an image.

Selecting Part Of An Image:

You edit the image in the Magnified Image Pane by selecting part of it and then doing something to what you have selected. The modifications will show up in all five differently-sized copies of the image.

There are two ways to select part of the image.

Use the mouse: Mousing down on one part of the image and dragging the mouse somewhere else before you release the button creates a rectangular selection, outlined by a "marching ants" or "marquee" border. Mousing down and releasing the mouse button without dragging creates a square selection that is four pixels wide and high, that corresponds to one pixel in the unenlarged image.
Use the "Select All" menu item, which selects the entire image.

The Color Well:

The color well near the lower left corner of the Percival window works in the standard way, with one exception: The feature that allows you to drag a color to the place where it will be used, can only be used to fill the current selection with color. That is, no matter where in the big square you try to drag the color to, it will end up in the current selection. (If you try to drag the color to a place outside the big square, it won't go anywhere at all.) I set the color well up to work that way because the four-by-four squares that are used to represent pixels of the full-sized image are so small that it might otherwise be hard to tell where the color was going; the selection provides a well-defined and easily visible target.

You may also change colors in the image you are editing by using the "Pour Color" and "Set Color" items of the Edit Menu, discussed later herein.

The "Use Transparent Color" Button:

The button near the lower-left corner of the Percival window, labeled "Use Transparent Color", is a short-cut for setting the color in the color well to completely transparent. You could do the same thing by clicking on the color well to bring up a color panel, then fiddling around with the controls on the panel. The button just does it faster.

This button does not change anything in the image you are editing. It only changes the color in the color well.

Menu Items:

The Percival Menu:

The items in the Percival menu are pretty much Apple standards. Only two require special discussion for Percival:

The "Consider Shareware Donation..." menu item opens up a window that reminds you that Percival is shareware, and tells you how to make a shareware donation if you should wish to do so. That window does not contain a slot for depositing money, nor does it attempt to access your bank account!
The "Quit" menu item allows you to quit from Percival. If the image you are working on has unsaved modifications, Percival will remind that you are about to lose your recent work, and will offer you a chance to change your mind about quitting.

By the way, Percival has no "Preferences" menu item: The program is so simple that I couldn't think of any preferences you might want to set.

The File Menu:

The File Menu items have to do with your interactions with Percival in the Percival window, and they are all quite conventional: "Open...", "Save", "Save As...", and "Revert" do pretty much what they do in most applications for the Macintosh, with pretty much the usual warnings if you are about to lose work or overwrite an existing file.

Two things deserve special mention:

First, Percival can only write TIFF files. If that is a problem, there are many other Macintosh applications which can convert image files from one type to another. Apple's "Preview" application, which is bundled with OS X as I write these words, has that capability. Apple's "Icon Composer" application can read TIFF files and use them to create icons. "Icon Composer" is bundled with Apple's "XCode" software development package as I write these words.
Second, the "Open..." menu item itself imposes no restrictions on the kinds of files that Percival can open. If you try to open a file that does not contain an image, or one containing some kind of image that Percival cannot read, Percival will tell you after you have selected the file. I arranged that this menu item work that way, rather than by making up a list of allowed file formats for Percival to use, to make sure I did not inadvertently leave out a format that Macintosh software could in fact read. There are a lot of image file formats, and Macintosh software can read many of them.

The Edit Menu:

The Edit Menu contains a few fairly standard items, and a few which are less conventional. None of the items in the Edit Menu will work until you have loaded an image. Until then, there is nothing to be edited.

The "Undo" and "Redo" menu items work pretty much the way they do in many Macintosh applications, but perhaps it will be useful if I present some details.
Percival keeps a record -- the technical name is "push-down stack" -- of how the image you have been working on has changed. It works like a stack of papers on your desk. Every time you load a new image, or make any modification of the image that you are working on, Percival puts a copy of the new or newly-modified image on top of the stack. The "Undo" and "Redo" commands let you get hold of a copy of whatever image you like from the stack; that way you can recover previous versions of what appeared in Percival's image panes.
The stack is not infinitely deep. It can hold only forty images. When the stack is full, then if you do something that would cause Percival to put another image on top of the stack, Percival will remove the image that is on the bottom of the stack to make room for the new one on top. The image that was on the bottom of the stack will be gone for good.
The "Copy" and "Paste" menu items only work within Percival. There is no direct way to use these items either to move data from another application into Percival, or to move data from Percival into another application. (But you can cheat! Load one image, use "Copy" to copy part of it, load another image, and use "Paste" to paste the copy into the new image.)
The "Copy" menu item makes a copy of the selection.
The "Paste" menu item pastes into the current selection, as much of the copied portion of the image as will fit, with the top left corner of the copy going into the top left corner of the current selection. Thus if the current selection is bigger than the copied portion of the image, the entire copied portion will be pasted into the top left corner of the current selection, and the rest of the current selection will be unchanged. On the other hand, if the current selection is smaller than the copied portion of the image, the pasted image will be cropped by the right edge of the selection rectangle, or by the bottom edge, or by both of these edges.
To put it another way, if you want to paste in the whole copied part of the image, make sure that the selection rectangle is bigger than what you want to paste.
The "Set Color" menu item sets the color of the entire selection to whatever color is displayed in the color well.
The "Pour Color" menu item only works when the selection is a single four-by-four square. The "Pour Color" menu item "pours" the color from the color well onto the image. Beginning with the selected square, the color spreads outward to all four-by-four squares of the same color as the starting square, that it can reach by crossing an edge of a square that it has already entered. The color will not enter a square by passing through a corner -- it has to have an edge in order for it to spill over.
The "paint bucket" icon on many Macintosh applications does very much what Percival's "Pour Color" menu item does.
A color-pouring feature is not as useful in an environment where there are millions of colors available as it was in the old black-and-white days. The reason is that the spread of color stops whenever the flow encounters a region that differs in color even the tiniest bit from the color of the area where the flow started. On the other hand, many icons are created in a style that has large areas that are all the same color; the "Pour Color" menu item will be useful for customizing these.
I disabled the "Pour Color" menu item when the selection is larger than a single four-by-four square so there would not be any doubt about where the color was going to go.
The "Select All" menu item selects the entire area of the big square for editing.

The Window Menu:

The Window Menu contains only fairly standard Macintosh menu items.

The Help Menu:

The one item in the Help Menu opens up an HTML help file which probably looks suspiciously like the one you are now reading ...

Tips and Hints:

Percival cannot cut and paste data to or from another application, but Percival provides an easy way to move data from one image file to another: Suppose you have two image files, "Source" and "Destination", and you would like to paste part of "Source" into "Destination". Load "Source" into Percival, use the "Copy" menu item to copy the part of the image you would like to cut and paste, then load "Destination", and use the "Paste" menu item to put the copy wherever you like. You can also use the "Undo" and "Redo" menu items to cycle back and forth between the loaded images of the two files. Just be careful to write the correct file when you finally save an image.
Master the color well! It is the essential tool for editing single pixels. Learn how to activate its color panel (single-click on the color well itself), play with the different color palettes in the color panel, learn to use the various sliders to change the color, and to use the magnifying glass to select a color you want from anywhere on the screen.
If you want to use the color of a single pixel in the image you are editing, it may be useful to use the mouse to select that pixel first. The border of the selection will be easy to see with the color panel's magnifying glass.
Sometimes, the easiest way to change the color of a pixel to another, more appropriate color, is to find a nearby pixel in the same image that is already the right color, make a copy of it, and paste it in place. Think of the image itself as its own best palette of appropriate colors.
Percival's selection rectangle stays the way it was last set until you make a new selection. That can be handy when you need either to make a new selection or to paste something in, just a few pixels away from the border of the current selection. Let the sides of the selection rectangle serve as customizable rulers to guide you.

Timeline:

What's New:

This section describes what is new in Percival since the previous release. I omit cosmetic improvements, minor changes in documentation and minor changes in displays.

Items are listed in more or less the order in which I dealt with them.

Since this is the first release, it's all new!

What Used to be New:

This section describes changes in Percival between its first release and the last one before what is now current. I omit cosmetic improvements, minor changes in documentation and minor changes in displays.

Items are listed in more or less the order in which I dealt with them.

Since this is the first release, there isn't anything that used to be new; it's all new!

What Might be New in the Future:

Besides fixing bugs and making internal improvements, my wish list for the future of Percival includes the following items, which are not necessarily in the order in which I might get around to doing them:

The ability to apply a Quartz color filter to the selection.
The ability to save images in other than TIFF format.

The future probably does not hold:

The ability to draw lines, curves, zig-zags, polygons, or other specialized shapes.
The ability to cut-and-paste from sources outside Percival.
The ability to work with more than one image at a time.

Miscellaneous Information:

I wrote Percival because I needed it, and stopped adding functionality when it would do what I wanted to do. Improvements and enhancements will likely also be things for which I have a use.

I have only written three or four stand-alone Macintosh applications, and Percival is the first one that allows editing images. Notwithstanding, it came up and ran in usefully in less than three days, by which I mean that three days after start of project I was able to perform the icon-editing task which had inspired me to write Percival in the first place. That speaks very well of the quality of Apple's "XCode" development environment. (The last stand-alone Macintosh application that I completed before Percival was an implementation of the Scheme Programming language called "Wraith Scheme" -- see my website for details -- that I have been fussing with off and on for twenty years, so my track record for average development speed is probably still a bit below average.)

It took about another week to polish things up and take care of the details well enough for Percival to be released as shareware. I could have added more features -- there seems to be no end to the list of possible features for an image editor -- but I have seen far too many software development projects succumb to one or another of the disastrous consequences of creeping featurism, so I decided to stop right there and release Percival 1.0. The first release has a rather minimal feature set, but it does a more than sufficient job at what I wanted it to do, so I hope others will find it useful.

Percival is written as a "Cocoa" application in a mixture of Objective C and C++, with a user interface developed with Apple's "Interface Builder" application. The program makes as much use as I could manage of Apple's enormous, Byzantine, and very useful, class library. Percival contains about 1500 lines of code.

Whimsy:

Excuses:

The following excuses may help explain flaws or omissions in Percival:

I do not possess your level of wisdom, insight or experience.
My computer is a Macbook; I did not test Percival extensively on other kinds of Macintosh.
I didn't think of that.
I forgot.
I was way too lazy.
I did not test Percival under older versions of Apple's system software.
I didn't know how.
I thought I knew how, but I was wrong.
I did it my way.

Infrequently Asked Questions:

"Why the name 'Percival'?"
I had cat named "Percival", of whom I was fond.
"Why name a program after a cat?"
It makes as much sense as naming a computer after a raincoat. (Mee-yow!!)
"Why are you so fond of cats, anyway?"
To those who understand, no explanation is necessary; to those who do not understand, no explanation is possible. Besides, they remind me that love can be unconditional, that innocence is worth protecting, and that curious optimism may discover a solution when greater minds would give up in despair.
"Why not release source for Percival?"
Portions embarrass me: How many cooks -- even good cooks -- want people to see what their kitchen looks like? (For me, cooking is not so much an art as a survival skill -- how to stay alive in the kitchen.)
"Do you think Percival will ever turn into a commercial product?"
I doubt there is enough market to warrant doing so.
"Why don't you ask for some particular amount in your request for a shareware donation?
I think it should be you who decides what my software is worth.
I might not even ask for shareware donations at all, except that I am curious who uses Percival, and where, and for what. I can get some idea of the first two by tracking shareware donations. Basically, I provide Percival as a public service: I won't go on about how I think people ought to make some such use of their time and energy, but I do think so. I work professionally in computer science and am presently doing okay (knock on wood). Putting a useful piece of software into the field is one way of saying "thank you" to a lot of people who have made things easier for me, and is perhaps a way to acknowledge and encourage many others who have missed various boats that I have been lucky enough to catch. The present implementation of Percival will set no records for high performance and will overwhelm no one with exotic features, but I suspect that some people may find it useful. So enjoy. And pass it on.
And if you are feeling guilty about not sending me a shareware donation, send me some EMail, and tell me how much you like Percival. Or if you don't like it, tell me why not and what I can do about it.
"Seriously, how much do you want for a shareware donation?
There is an old Russian proverb: "Hope for the best, and expect the worst; thus you shall never be disappointed."
"Tell us something about yourself."
Life happens while you are making other plans: I am a retread astrophysicist who has worked as flight instructor, consultant to the U. S. Department of Energy, and computer scientist. My doctoral thesis project used a spacecraft instrument (1975 Apollo-Soyuz Test Project) to study the interstellar medium.
My introduction to computer science was writing small Fortran programs to reduce thesis data. (I thought they were big Fortran programs at the time.) I have worked on parallel processing -- SIMD and MIMD, hardware and software. I once helped build a CyberSpace interface. I have worked in what marketeers call "artificial intelligence" but is better termed "system programming in Lisp". And I have won Rogue many times, without resorting to Wizard mode.
I am a science fiction fan, an English Regency ballroom dancer, and an occasional bicyclist, rose grower and amateur astronomer. I play guitar and occasionally build simple musical instruments. I live in Palo Alto, California, with too many cats and not enough time.
Answers to commonly-asked personal questions: blue, chocolate, chunky, single, and only if the esteem is mutual.
I have a personal web site: http://web.mac.com/Jay_Reynolds_Freeman.
"Are you planning any more projects?"
Well, the garden needs some work, and... oh, you meant programming projects. Let's just say that I have had lots of cats.

Thanks To:

(Note that the cats have the last word.)

Apple Incorporated, for providing excellent software development environments and numerous examples of code, all for free. (Notwithstanding, I expect that all errors and misfeatures in Percival are my fault.)
Percival, and numerous other cats, for love and purrs, and for the sharing of their ineffable names.

-- Jay Reynolds Freeman, February, 2007