Home Page
Projects > Picture Viewer
Picture Viewer Thumbnail
Picture Viewer v1.0.1
“Picture Viewer” cycles through a compiled list of image files for viewing at set intervals. Images can also be overlaid on the screen, and this can also be used as a screen saver.
Rating: 9 (Lots of configurable and toggle-able options to make the program more versatile. Can be used to replace standard Windows Picture Viewer or as a screen saver.)
Project Time: 8/31/2009-9/9/2009: 10
Languages: Python
Requirements: (When Running From Source): Python, PIL, PyWin32
Downloads: Binary Source (See any updates below for prior versions)
Sections: Information, Content, Concepts, Notes, Updates, Comments
Features Include:
  • Set multiple paths to include/exclude
  • Overlay image on top of current screen
  • Select translucency of window
  • Ignoring user input when form is not selected (and quickly access form through shortcut key)
  • Sort images by (File): Path, Name, Modified Date, Created Date, Random
  • Choose where to display the image on the screen
  • Constrain image proportions (for all or only larger than screen) to fit screen
  • Display file name and save to clipboard
  • Set image cycling time and pause cycling
  • Global and local shortcut keys for most options
  • See Configuration Options for more options

The following is the configuration options for the program, and instructions on how to run and compile the program from source. The configuration options can be modified through the “PictureViewer.cfg” file, which only supports standard ASCII.

Name DefaultValues Description
Files to Include and in What Order:
Include -   Path List of files to include (See How Path Lists Work)
Exclude -   Path List of files to exclude (Overwrites all includes, See How Path Lists Work)
Extensions -   List of valid extensions that are included as pictures when searching a directory. Non alphanumeric characters are removed. See the Python Imaging Library for supported formats
Sort Random See Descr. The order in which to display the images. The value can be one of the following: Path, Name, Modified, Created, Random
StartOn 0 Integer The index number of the image in the File List to start display on
SaveStartOn Yes Yes,No Whether to update the StartOn option in the configuration file when the program shuts down with the index of the last displayed image
How to display the image:
Position 5 1-9 The position on the screen where the image is displayed (See How Positions Work)
Background No Yes,No If Yes, any area on the screen not taken up by the picture is filled with this color
BGColor 0 ColorValue The color that fills the background (when toggled) (See How Colors Work)
IsOpaque No Yes,No If Yes, the window is opaque and can be clicked. Otherwise, it is an overlay with Translucency% opacity and cannot be clicked
Translucency 50 0-100 If the IsOpaque option is No, the window has an alpha blended translucency of the given percent
FitToScreen No Yes,No Whether to stretch all images to fit the bounds of the screen (aspect ratio is maintained)
ShrinkToFit Yes Yes,No Whether to shrink an image that has a width or height that is larger than the screen (aspect ratio is maintained)
When to display images:
Interval 10000 Integer An integral number that determines the number of milliseconds between changing images. 0 means do not change. 1000 is 1 second.
Cycle Yes Yes,No Whether to change to the next image after each Interval. If turned off, the image can only be changed manually by the user
How to display text:
DisplayName No Yes,No Whether to display the file path on the screen
NamePosition 2 1-9 The position on the screen where the file path (if toggled) is displayed (See How Positions Work)
FGColor FFFFFF ColorValue The color that is used to display text (the file path [if toggled] or help information) (See How Colors Work)
TextUsesBG Yes Yes,No If Yes, text (the file path [if toggled] or help information) is printed over the BGColor
Other Options:
ExitOnActivity No Yes,No If Yes, any mouse or non-bound-keyboard activity will shut down the program
Preload Yes Yes,No Whether to load the next image to display in memory as soon as is possible (removes lag, increases memory footprint). This setting is currently not supported.
All bold red configuration options have shortcut keys used to modify their values during runtime (see Normal Shortcut Keys). These updated values are not saved back to the configuration file.

Shortcut NameDefaultDescription
Special Shortcut Keys: (See How Shortcut Keys Work)
LKeyQuit ESC;Q Quit the application
LKeyNameToCB C Copy the filename to the clipboard
LKeyInfo I;H Display the help/information screen. Use this to see current configuration options (especially when increasing/decreasing numerical values)
LKeyNext SPACE;RIGHT Move to the next image
LKeyPrevious LEFT Move to the previous image
LKeyZoomIn = Zoom current picture 10% in
LKeyZoomOut - Zoom current picture 10% out
GKeyGetFocus CTRL+SHIFT+P (Global only) Give the window focus so local shortcut keys work
Normal Shortcut Keys: (These all modify above configuration options) (See How Shortcut Keys Work)
LKeyCycle ENTER See the Cycle option. This essentially pauses the automatic progression of the images
LKeyTranslucencyU NUM+ See the Translucency option. Increases the translucency
LKeyTranslucencyD NUM- See the Translucency option. Decreases the translucency
LKeyDisplayName N See the DisplayName option
LKeyPosition1 NUM1 See the Position option. There are also configuration options for LPosition2-9
LKeyBackground B See the Background option
LKeyIsOpaque O See the IsOpaque option
LKeyFitToScreen F See the FitToScreen option
LKeyShrinkToFit S See the ShrinkToFit option
LKeyIntervalU ] See the Interval option. Increases the interval by 100ms
LKeyIntervalD [ See the Interval option. Decreases the interval by 100ms
LKeyNamePosition1 CTRL+NUM1 See the NamePosition option. There are also configuration options for LNamePosition2-9
LKeyTextUsesBG T See the TextUsesBG option
LKeyPreload P See the Preload option

Misconfiguration and Errors:
  • All errors in the configuration file and during runtime are reported to “PictureViewer.err” in the same directory as the executable.
  • The error file only contains an error report from the last run of the program.
  • If the program has no image files it can display, it displays a message box error to the user and exits out.

  • Description:
    • A “Path List” is used to compile a list of files (“File List”) from a list of directories and files separated by semicolons “;”.
  • Items In a Path List Can Be:
    • A path to a file: Includes a single file
    • A path to a directory (trailing slash ignored): Includes all files in the directory
    • A path to a directory with a “*” for the file name: Includes all files in the directory and its sub directories recursively
  • Conditions and Restrictions:
    • If a file is included more than once in a Path List, it will keep multiple entries in the final File List.
    • Directories in a Path List can be separated by either a “/” or a “\”.
    • Any directory or file names in a Path List cannot contain semicolons or slashes.
    • When searching through a directory, only files with proper extensions are kept (See the Extensions option).
    • All Unicode files and paths under the primary path are supported.
    • Paths in the Path List can be relative to the executable, or absolute to the operating system.
  • Example:
    • Example Paths and Files:
      • C:\Images
        • A.bmp
        • B.jpg
        • SubFolder\
          • C.png
          • D.txt
    • Example items in a file list:
      PATH Description Includes In the File List
      C:\Images\A.bmp Single file C:\Images\A.bmp
      C:\Images Directory (No  Recurse) C:\Images\A.bmp, C:\Images\B.jpg
      C:\Images/ Directory (No  Recurse) C:\Images\A.bmp, C:\Images\B.jpg
      C:/Images/* Directory (Yes Recurse) C:\Images\A.bmp, C:\Images\B.jpg, C:\Images\SubFolder\C.png

  • The position determines where on the screen something is displayed.
  • Its value is a number whose position on the screen is determined by a typical keyboard number pad layout. (Ex: 5=center)

  • A hexadecimal representation of a color in the format RRGGBB (red, green, blue).
  • For Example, “FF0000” is red, and “FF8000” is orange (all red, half green).

  • Each listed shortcut configuration option actually has 2 configuration operations:
    • 1) A local shortcut
      • These only activate when the window has focus. They start with “LKey”, for example, “LKeyQuit”.
    • 2) A global shortcut
      • These can be activated even when the window does not have focus. These start with “GKey”, for example, “GKeyQuit”.
      • These are not listed above because there is one corresponding global shortcut for every local shortcut, and they are all bound to “NULL” by default.
      • Whenever a global shortcut is activated, its keystroke does not reach other windows.
  • Shortcut keys can be separated by semicolons “;” to bind multiple keys to one action.
  • A shortcut key value can be preceded by any of the following toggle keys: “CTRL+”, “ALT+”, “SHIFT+”, “WIN+”. If one or more of these toggles is included, that/those toggle key(s) must be held down for the shortcut to be invoked.
  • “NULL” (or blank) can be given as the value to not bind a key to a shortcut.
  • The list of possible key values are as follows (case insensitive):
    • Ranges: A-Z, 0-9, NUM0-NUM9, F1-F24
    • Symbols: ` - = [ ] \ : ' , . /        #Note “:” is used instead “;” to avoid listing issues
    • Non standard symbols keys: ! <
    • Number pad: NUM+, NUM., NUM/, NUM*, NUM-, NUMLOCK
    • Other normal keys: Esc, Pause, Break, PrintScreen, Insert, Delete, PageUp, PageDown, Home, End, BackSpace, Tab, CapsLock, Enter, Up, Down, Left, Right, Space, ContextMenu, ScrollLock
    • Vendor specific: VolumeDown, VolumeMute, VolumeUp, Media, NextTrack, PreviousTrack, Play_Pause, Stop, BrowserBack, BrowserFavorites, BrowserForward, BrowserHome, BrowserRefresh, BrowserSearch, BrowserStop, App1, App2, Mail
    • Others: Abnt_C1, Abnt_C2, Attn, Clear, Cr_Sel, Er_Eof, Execute, Ex_Sel, IcoClr, IcoHlp, NoName, Oem_Attn, Auto, Ax, Back_Tab, OemClr, Copy, Cu_Sel, Enlw, Finish, Loya, Mashu, Roya, Touroku, Jump, OemPa1, OemPa2, OemPa3, Reset, WsCtrl, Pa1, Packet, Play, Process, Select, Separator, Zoom, Accept, Convert, Final, Help, Ico00, Junja, Kana, Kanji, Mode_Change, Non_Convert, Jisho, Print, Sleep
    • Mouse: LButton, RButton, MButton, XButton1, XButton2

Dependencies: (When running from source)

  • ./PictureViewer.py

To Compile: (py2exe required)
  • python setup.py py2exe

Example Screenshot of Overlay Mode with Info and Name turned on:
Example Screenshot of Overlay Mode with Info and Name turned on
Windows APIs
Python wasn’t really built to utilize normal (C based) DLLs and Windows APIs. It’s really clunky to use both of those... but oh well. It’s an interesting language.
Picture Viewer v1.0.1 @ 2010-01-24 08:48:45 - Download

v1.0.1: Binary Source

Fixed an infinite loop when displaying a picture’s file name that occurred when the width was too small for even 1 character to be displayed.

Added interrupt signal handling, even though it doesn’t work too well in Windows :-\.

Dakusan License v2.0 @ 2009-11-04 16:06:57 - Download

I have updated the licensing information across the board for my website and all its projects to the Dakusan License v2.0, a slightly modified version of the Original BSD License.

The Copyright page and all project downloads have been updated accordingly.

Added Readme files to all project downloads @ 2009-09-19 05:35:19

Binary and source zip downloads for all Projects now have readme files in them, except as mentioned below.

This only applies to the Draw Image Project in Web Scripts, and not the Directory Manager project (The only project zip file now without a readme).

Picture Viewer v1.0 @ 2009-09-10 04:37:21 - Download

Here is the initial v1.0 (source) public release of my Picture Viewer project. See its project page for more information on what all it does.

I’ve wanted to try out Python for a while now, as it has been recommended to me by multiple friends. I decided to redo an old Visual Basic [6] project I did way back in October of 2002 in Python for this reason, and also because I used it every now and then and was frustrated by all the features it was missing that I wanted (I had been meaning to redo it in C++ for a while).

The original project was done as a request from a friend, and was completed in a couple of hours. It only had 5 settings that it read from a config file that had to be in a proper order, and had pretty much no interactivity, but it was a novel idea I had not seen implemented well elsewhere.

For this new version, I started out by listing over a dozen options and configurations I wanted from this redo of the project and compiled the readme and configuration file from it. From there I built the configuration file reader/parser. These 2 parts of the project actually ended up taking more time than the rest of the application programming itself ^_^;. The actual GUI/interactivity part was the quick part of the project.

This new iteration of the project is much more versatile, configurable, and robust. Most all of the options are changeable both through the configuration file, and through keyboard shortcuts set in the configuration file. It is set up to be used as both a picture screen saver, or just as a picture viewer.

I spent a good chunk of time also playing around with compiling python files for Windows for binary release (py2exe), the options for it, and reducing the final size of the distribution. I was able to get the final project distribution size from 5.8MB down to 1.83MB (including upx packing). There was a lot of trial and error to get it down to an acceptable size, including finding a lot of package distribution/compiling options, which aren’t very well documented, and determining which included Python modules and DLLs were not being used and could be excluded. Setting and retrieving file version information wasn’t really documented either, and I even had to do some hacking (dynamic class reconfiguring) to include some file version information that was not being included that should have been.

The final distribution could be made a lot smaller still by removing some of the modules I used. The PyWin32 information could all be included through ctypes and manually including Windows32 constants (win32con). The Python Imaging Library (PIL) module could also be completely removed and replaced with Windows graphics APIs, but it would really have been a pain. PIL included support for a good number of graphics formats, and hooking up with Windows GDI+ through Python would been a major pain in the ass, so in the end, for this project, being able to quickly get everything done won out.

There are a number of things I’d still like to get implemented in this project that I’m just not going to worry about right now. Those include:
  • Command line option overrides (Override all options that can be set in the configuration file)
  • The “ExitOnActivity” option (for screen savers) doesn’t work outside the window (when the “background” option is turned off). If the mouse does not travel over the window, it will not close from mouse movements.
  • I ended up decided on not implementing next-picture preloading yet (though it is included in the configuration file). This would be especially useful for “picture viewer” mode, as moving to the next picture when the user presses a key would [usually] have [virtually] no load time.
  • It would be better if pictures started displaying immediately upon application load (whenever the first picture is found) instead of waiting for the entire “File List” to load.
  • Checking for interrupt/exit signals
  • Reading the configuration file from different (and multiple) paths
  • Get Unicode working in the configuration file
  • Resorting images
  • Go back to last the focused window

This project was originally named on this site “Picture Screen Saver”. Its entry has been completely updated including changing the rating from a 4 to a 7. The content section of the project page now reflects the readme file found in the project’s downloads.

To add comments, please go to the forum page for this project (guest comments are allowed for the Projects, Posts, and Updates Forums).
Comments are owned by the user who posted them. We accept no responsibility for the contents of these comments.

No comments for this Project