repo-iconify

A simple shell script that overlays text over an image, for use in creating unique logos for your VCS repositories.

Example

The easiest way to describe what this does is to show an example. This is the logo for this repository.

It was generated with the following configuration, stored within a .repo-iconify file in the current directory.

InputFile=~/.face
Color=white
Background="#EF6C00"
Text=ICON
Direction=east
Suffix=" "
Offset=+0-70

This file can be summarized as follows:

• The base image (input file) is my Linux profile picture, found in ~/.face
• Text color is set to white
• Background color is set to a hex value, which is a shade of orange
• The actual text contents is the word "ICON"
• Direction (location of text) is set to east (the right of the image)
• After $Text, the suffix (a single space) is added for spacing
• Offset is set to horizontal: 0px, vertical -70px. This has the effect of shifting the text up 70 pixels

Full Specification

Generate an icon by running repo-iconify in the current directory. To get a good looking one, you will want to specify preferences in a .repo-iconify configuration file. On runtime, repo-iconify traverses through the directory tree, and applies all configurations found within, prioritizing ones lower down (closer to the current directory).

Options

The following is a list of options than can be specified in a .repo-iconify file.

• InputFile Path to image source
• Color Color of text
• Background Color of background
• Outline Color of text outline
• Text Text string, required nonempty
• Prefix Prefix to text
• Suffix Suffix to text
• Point Text size, in pts
• Stroke Outline weight, in pts (acts as text weight if outline color is same as text, as default)
• Direction Text position, one of {north, south, east, west, northeast, ...}
• Offset Offset from direction, horizontal then vertical concatenated. Example: -10+20 means left 10 pixels, down 20 pixels
• OutputFile Path of image output, with file extension (proper file will be created, depending on extension given)

As a .repo-iconify file is simply a script that is executed, these options can be complex and reference each other, as well as other macros provided, like so:

Direction=east
Offset=+0-$((Height / 4))

The $(( ... )) operator is the Bash arithmetic operator, and thus we are shifting the text up 1/4th of the height of the full image, centering it on the north-northeast line.

Macros

The previous point brings up the subject of macros, which are procedurally generated variables you can use in your configuration files. These are:

• Root=true Setting Root to true in a configuration sets the current directory as pthe root of the configuration tree, and prevents further traversal up the directory tree in search of higher configuration files
• GenerateImageData Placing this line in a configuration file, provided that InputFile has already been defined in that file or in a higher file, and provided that that file exists, generates the following macros for your disposal:
  • Height Height of the image, in px
  • Width Width of the image, in px
  • MinDim Minimum dimension, the minimum of Height and Width
• FullText This variable should not be declared in most cases, as it is generated by the program as the concatenation of Prefix, Text, and Suffix. However, if it is overwritten in a config, then Prefix, Text, and Suffix are ignored.

Defaults

In lieu of any modifications within a .repo-iconify, these are the default settings given. Note that this will not work, as Text is set empty, and thus the program will error out.

InputFile=~/.face
Color=white
Background=black
Outline=$Color
Text=""
Direction=east
Offset=+0+0
OutputFile=logo.png
Point=$((MinDim * 7 / 10 / 4))
Stroke=$((Point / 20))
FullText="$Prefix$Text$Suffix"

The Point field is set as the minimum dimension of image, multiplied by 0.7 (which is the approximate point/pixels ratio, 7.5 pt font being 10 px high), and then divided by 4, to make a quarter of the minimum dimension (which, if the minimum dimension is height, is equivalent to the quarter the height of the image).

The Stroke is set to 1/20th of the Point, which is slightly bold.

Command Line Arguments

Although, with the default configuration, repo-iconify will not process (as $Text is not specified), you do not need to create a .repo-iconify configuration file yourself to use this utility. An easier way is to specify command line arguments on runtime to repo-iconify, and the program will append (or replace) these options in the local (current directory) .repo-iconify config and then execute them with these changes reflected. For example, the icon displayed at the top of this README could have been accomplished with running:

repo-iconify Color=white Background="EF6C00" Text=ICON Suffix=" " Offset=+0-70