   CherryBrush 0.25 by DrPetter
----------------------------------
        drpetter@gmail.com
      http://www.drpetter.se
----------------------------------
           2009-09-18


Contents
--------
Requirements
Instructions
 - Navigation
 - Drawing
 - Animation
 - Color profiles
 - Filters
 - Layers
 - File operations
Troubleshooting
--------



 Requirements
 ------------

Graphics card with decent OpenGL performance and a reasonable amount of texture memory. 32 MB is probably a minimum. 64 MB should be enough for relatively large images.


 Instructions
 ------------

 Navigation

Hold Space to scroll or rotate the canvas, depending on whether you click inside or outside the navigation circle. Shift+Space resets rotation to zero. Use numpad +/- or mousewheel to zoom. Press numpad * to reset zoom to 100% and center the image on screen. Press F to flip/mirror canvas horizontally, this is a visual effect only and doesn't modify the image content. Flipping the image helps you keep track of proportions with a fresh eye.

Click the triangle-labeled button near the upper right corner to toggle showing an overview of the whole canvas. This overview can be resized by dragging the handle in its lower-right corner.


 Drawing

Draw on the canvas using left mouse button or tablet. X switches foreground/background colors. Clicking the "E" or "B" right of the swatches will toggle eraser. You can also toggle erase using the E key, or erase with right mouse button or the tablet eraser. B also selects normal paintbrush if you're using the eraser. The eraser can be toggled (X) between normal and "inverted" mode, where it draws back opacity instead of erasing it. This leads to some peculiar effects if you bring back areas that have never been painted on, as they will be default white.

Hold Shift while drawing to constrain lines to horizontal/vertical. Shift+click will draw a line from the end of the previous line.

Press Ctrl+Z to undo the most recent brush stroke. There are 16 levels of undo and as for now they are cleared/forgotten whenever you remove or merge a layer.

Click foreground swatch in upper left corner to manually adjust the current color.
Hold Alt to enter color-picking and brush property mode. Click to pick colors you see from the canvas, hold Alt+Shift to pick colors only from the current layer. Color-picking is pressure sensitive, so you can partially blend towards a color if you touch it lightly.
The colors shown in the hovering box are accompanied by borders showing their normalized hue and saturation properties, with constant value. This is especially useful for judging the character of very dark colors.

While holding Alt, mouse over the hovering color preview area to adjust brush settings. Click and drag in the box that appears - up/down is size, right/left is hardness. Hold Shift while doing this to select a "pixel brush" which has no antialiasing or pressure sensitivity. This will also change the display to a non-filtered mode.

Also while holding Alt, you can press Ctrl to enter layer selection mode. Move the mouse cursor over the image and click to select a layer visually. The hovering box will show a preview of the layer you're hovering over.

To the right of the color preview is a slider which controls pressure scale, drag this down to reduce maximum pressure (this will also affect mouse input). Alt+mousewheel is shortcut for this slider.
The buttons below the color preview toggle various brush effects. The right-most one labeled "Bi" enables inertia, which smooths out brush movement to help make nice curves. "Bs" is variable brush size, where pressure controls brush size and opacity is always at maximum. Use both triangle and square for smooth variable-width ink lines.
"Av" is line avoidance, which works like the variable-sized brush except it will automatically shrink to avoid drawing over lines on layers above the current one. Can be useful for some coloring tasks.
"Jy" activates joystick-controlled pressure, which might be useful if you don't have a tablet. It will use the first available joystick, and you can select which axis to use by wiggling it after pressing this button. Make sure you keep the axis at rest position before you click it (this also allows an inverse mapping of that axis, if you hold it at maximum before clicking).

Ctrl+click will do flood fill, which works in slightly different ways depending on the situation. It will generally fill the clicked color area with your foreground color, but it will also stay within any opaque areas of layers above the current one. This means that you can easily fill inside line art on a color layer placed beneath the lines. Note that it's also possible to erase-fill when you're in eraser mode.


 Animation

Toggle animation mode from the Settings menu. When you're in animation mode each floating layer (not the bottom canvas) will get a button labeled "A" that selects whether it's animated or not. An animated layer will have as many frames as the whole animation, indicated in the animation toolbox at the bottom of the main window. You can add or remove frames, and change their duration. Switching a non-animated layer into an animated state will keep the displayed image (if any) as the current frame and make all others empty.

Use the keyboard arrow keys to navigate between frames. Right/Left will step one frame at a time. Down will play the animation forward, and Up will play it backward.

You have the option of displaying an "onionskin" which will show ghost images of the next and previous frames as guides for drawing new frames. If you select an existing frame in the middle of the animation and add a new one, you will get an empty frame between two existing ones, and you can draw an intermediate "tweened" frame based on the two onionskins.

There are two buttons for exporting your animation. The "Export" button will simply save each frame as an image, while "Export full" will repeat frames with duration greater than 1, to allow full reconstruction of the animation in a different application, with timing intact.

All normal drawing operations work as usual. Undo history is cleared as soon as you do any frame navigation (even if you just move to a different frame). This is a temporary feature - I will try to make undo work for drawing operations performed on arbitrary frames despite any basic navigation done, as long as you don't remove frames.


 Color profiles

Just select one from the menu and try it out. Conversion between profiles is technically lossy, so you shouldn't do it all the time. It rarely causes any noticable quality degradation though, but changing to one of the extreme configurations like Neon can hurt some images. Be sure to save a backup copy before playing around with important material. The color profile used will be saved and loaded with PSG files. Note that changing color profile will affect all "live" blending, which essentially means new brush strokes, transparent layers and color picking/mixing. Anything already painted into an opaque image will look the same.


 Filters
Select from menu. Configure parameters in the popup box and press OK or Cancel to apply/revert. You can undo these.

The blur filter has no live preview since it's rather slow on large images.

Transparency noise will remove a noise pattern from the transparency mask of a layer, use this to overlay colored noise in various ways by painting on a layer and then applying this filter.

Greyscale mask converts an opaque greyscale layer into a fully black layer with white areas transparent (actually just uses the red channel at the moment). This is intended for coloring line art - you can load or paste an image, then copy-paste the bottom layer into a hovering one (just press Ctrl+C followed by Ctrl+V), then apply this filter to the hovering layer to allow coloring underneath the lines using various convenient fill tools. It's often necessary to adjust the levels of the initial greyscale image before applying the filter, to blow out any subtle JPEG compression artifacts and other impurities. Usually you can safely crop out the top and bottom 10% or so of the intensity range without any noticable degradation in line quality.


 Layers

Use the buttons provided to manipulate the layer stack. You can add layers (+), remove them (x) and merge a layer with the neighbor below it (down arrow icon). Ctrl+E is shortcut to merge the current layer. Change the opacity of a layer by dragging the black slider up and down. By clicking the 'T' icon, you can lock the layer transparency mask and only allow color alteration. This is very useful for coloring/rendering objects which already have a determined silhouette. Merged layers will automatically have their opacity baked into the image data, so you should generally make sure that two layers to be merged are set up to look correct before you merge.

Layers can have different blending modes which determine how they combine with the underlying layers. Only "Normal" is guaranteed to work as expected when merged with a semi-transparent layer. Others will likely preserve transparency of the bottom layer and just modify its colors. If you want to merge with other types of blending, try having an opaque bottom layer if possible (merge bottom-up instead of top-down).

You can rearrange the layer order by clicking and dragging a layer and dropping it at the desired spot. The bottom layer acts as a solid base to all layer operations and can not be moved or made transparent. Ctrl+C and Ctrl+V can be used for copy/pasting layers, but not between image sessions (i.e. can't paste after new or load).

Ctrl+V can also be used to paste a bitmap from the Windows clipboard, if there is one and you don't have any copied layers since earlier. The canvas will be reset to the pasted dimensions and all layers removed (basically New image).


 File operations

Ctrl+N        -  New image
Ctrl+O/Ctrl+L -  Load
Ctrl+S        -  Save
Ctrl+Shift+S  -  Save as...
Ctrl+R        -  Revert (reload current image file, if you regret everything you did after the last save)

Supported image formats are PSG (internal layered format), PNG and JPEG.

Saving a layered image to a format that doesn't support it will automatically produce a flattened image file. You can then continue working with your layers, but remember to save as PSG if you want to keep the layer structure for another session. It's also sensible to work with a lossless layered file if you want to use the revert function.


 Troubleshooting
 ---------------

There were reports of poor line quality/jitter when using a Trust tablet, so I added a setting in config.txt to force mouse coordinates for drawing instead of sampling directly from the tablet. This seemed to help, and made the lines steadier. A drawback is that the sample rate will not be higher than your mouse rate, which is typically 60 Hz, so curved lines might become more polygonal than they would be with a high tablet sample rate.
Open config.txt and change the value of force_mouse_coordinates from 0 to 1 if you want to use this setting.

