Permalink
Fetching contributors…
Cannot retrieve contributors at this time
217 lines (144 sloc) 8.17 KB

header

Speculid

Twitter Codecov homebrew Travis Beerpay Gitter Analytics

Easily Build Xcode Image and App Icon Assets from Graphic Files.

Table of Contents

Requirements

  • macOS 10.10 Yosemite
  • Xcode 8.0

Synopsis

diagram

Part of the process of building an app for watchOS, iOS, or macOS is including all the image assets in your application. That could be done by exporting the various sizes from your graphics application. However including the exporting process in the app build, provides many benefits:

  • Saving Time On Pulling The Repository:
    • exported graphics don't need to be included with source control
  • New Graphic Will Be Automatically Used After Build:
    • every time a modification is made to the source graphic, the build process will update the assets
  • Exporting The Image Assets No Longer Part of Graphic Design Process:
    • when editing the source graphic, exporting is moved to build process

Speculid gives you the ability to run a script which builds those assets from a jpeg, png, or even vector graphics file like svg.

Installation

Speculid can be installed via Homebrew <http://brew.sh/>:

$ brew tap brightdigit/speculid
$ brew install speculid

Features

  • Parse App Icon and Image Sets
  • Convert SVG Files to Designated Sizes
  • Resize Raster Images to Designated Sizes
  • Command-Line Capabilities for Creating Build Phase Scripts

Usage

$ speculid <file>
$ speculid --help
$ speculid --version

Options:
  -h --help     Show this screen.
  --version     Show version.

File Format

The .speculid file is a json file with the image set or app icon path, the graphic file source, and optionally the basic image geometry (width or height). Such as

{
  "set" : "Assets.xcassets/Raster Image.imageset",
  "source" : "layers.png",
  "geometry" : "128"
}

or

{
"set" : "Assets.xcassets/iOS AppIcon.appiconset",
"source" : "geometry.svg",
"background" : "#FFFFFFFF",
"remove-alpha" : true
}

Set set

Image Set Examples from Xcode

A set is an image set or app icon set used by Xcode. That path specified in the json could be relative to the .spcld file.

Source source

The image source file which could be a SVG or any bitmap image type compatible with imagemagick.

Geometry optional geometry

The destination geometry of image if needed (i.e. image set). It must be in the format of:

  • width (ex. "128") - for specifying the width of the destination image
  • xheight (ex. "x128") - for specifying the height of the destination image

You can only specify the height or the width. The other dimension is automatically calculated based on the aspect ration of the image.

Background optional background

As a requirement, App Icons are required to exclude any alpha channels. In order to remove a transparency from a source png or svg file, you can specify to remove the alpha channel and add a background color. The background color can be set with a string in a standard rgb, rgba, or hex code format (#RRGGBB or #AARRGGBB). If no alpha is specified an alpha of 1.0 is assumed.

Remove Alpha optional remove-alpha

To specifically remove the alpha channel, a true boolean value must be specified. This will remove the alpha channel from the file. Make sure to specify an opaque background color when removing the alpha channel.

Application Configuration

If you install Speculid using the standard homebrew path, it should be able to find the nessacary applications needed. However if you need to set the path to the dependency applications, create a json file in your home directory /Users/username/ named speculid.json. Then specify the paths to the application dependencies:

{
  "paths" : {
    "inkscape" : "/usr/local/bin/inkscape",
    "convert": "/usr/local/bin/convert"
  }
}

If you are uncertain the paths, in your terminal run which <command> and it will tell you the complete path to the application.

$ which inkscape
/usr/local/bin/inkscape

If you are interested in a more automated method, up vote the issue here.

Xcode Integration

With Speculid, the process of building image assets can be automated in Xcode.

  1. Add the speculid files to your source root as well as your source graphic files.

Xcode Target Membership

  • Note: you don't need to add these files to your target membership
  1. Add the Run Script Build Phase to the top of your project with the following code:

    find "${SRCROOT}" -name "*.speculid" -print0 |
    while IFS= read -r -d $'\0' line; do
    speculid "$line" &
    done
    wait

    Xcode Build Phase Run Script

  2. Build the application. This will create the graphics which you will use in your asset image set or app icon.

Xcode Unorganized Assets

  1. Drag the images to the correct asset slot. Each rendered image file is suffixed denoting its slot.

    (source file base name).(size)@(scale)~(idiom).(extension)

    Examples

    • logo.20x20@1x~ipad.png - 20x20 size 1x scale for iPad
    • logo.60x60@3x~iphone.png - 60x60 size 3x scale for iPhone
    • logo.83.5x83.5@2x~ipad.png - 83.5x83.5 size 2x scale for iPad
  2. Build and Run. Done.

Dependencies

  • Inkscape — a professional vector graphics editor
  • Imagemagick - a software suite to create, edit, compose, or convert bitmap images

Thanks

Speculid © 2016, BrightDigit, LLC. Released under the MIT License.

brightdigit.com  ·  GitHub @brightdigit  ·  Twitter @brightdigit