jondot / blade Goto Github PK

Better asset workflow for iOS developers. Generate Xcode image catalogs for iOS / OSX app icons, universal images, and more.

Makefile 3.85% Go 92.67% Ruby 3.48%

blade's Introduction

Blade

Automatically build and rebuild Xcode image catalogs for app icons, universal images, and more.

Use in existing projects to generate image catalogs with no extra work. Blade will automagically refresh your image catalogs based on given master images.
Use templates of image catalogs to generate new catalogs (see templates).

See blade-sample for a preconfigured project.

Why?

Because most of the time your image catalogs are the same image, resized to various sizes.

Here is how people solve this usually:

Have the designer slice the images manually / automatically using a PSD template
Use some sort of online image slicing service which emails you a zip of the various sizes

The problem with these solutions is:

Some times the various slices are not up to date with Xcode (new devices, new sizes)
It Almost always require extra work from you (placing each image manually in the catalog, fixing mismatches etc.)
You can't control the quality of the resize
You can't integrate the tooling into your build workflow or CI

Blade is an open source tool which will replace the PSD template and/or online services for you, and has a goal to satisfy the above requirements in the best way possible.

Quick start

You have 2 ways to install:

Homebrew

Using Homebrew:

 $ brew tap jondot/tap
 $ brew install blade

Release

Download one of the binaries in releases, and put in your PATH or just include in each Xcode project's root.

This should be a typical run of blade:

Use a Bladefile

Here's how a project setup with a Bladefile feels like (more in the Blade Sample repo):

The best way to use Blade, is to set up a local Bladefile for your entire project. Within it, specify all of your resources. Blade will pick it up automatically.

See blade-sample for a preconfigured project.

$ blade --init
Wrote Bladefile.

Here is how your Bladefile would look like:

blades:
  - source: [email protected]
    mount: foobar/Assets.xcassets/AppIcon.appiconset
  - source: Spaceship_1024.png
    mount: foobar/Assets.xcassets/Spaceship.imageset

It was made for this project structure:

foobar
├── Bladefile
├── images
│   ├── [email protected]
│   └── Spaceship_1024.png
├── foobar
│   ├── AppDelegate.swift
│   ├── Assets.xcassets
│   │   ├── AppIcon.appiconset
│   │   │   └── Contents.json
│   │   └── Spaceship.imageset
│   │       ├── Contents.json

Then use Blade (use --verbose if you want logs) within the same folder where your Bladefile lives:

$ blade --verbose
INFO[0000] Found a local Bladefile.
INFO[0000] Bladefile contains 2 blade defs.
...

And it will generate all of the images needed within each image catalog.

To make this happen before each build see how to run a script while building a product

Use directly

$ blade [email protected] --template=templates/watch.json --out=out/watch --catalog

Here's what we did:

Use a source image (--source)
Make a brand new image catalog (--catalog), from a template (templates/watch.json)
Put everything in out/watch

$ blade -s [email protected] -t existing.imageset -o existing.imageset

Here's what we did:

Use a source image (-s)
Point to an existing image catalog (-t)
Output to that same existing image catalog (-o)
In other words, Blade will refresh the images in this catalog

How does it work?

Blade parses the same Xcode image catalog configuration file as its own configuration source - no new concept introduced. This allows it to be future-proof with Xcode updates for new image sizes and catalog types.

Supported workflows:

Prototyping ad-hoc, while prototyping projects
Development build with Build Steps, transforming all of your source image assets to image catalogs
CI in your CI servers, either on OSX or Linux (though Linux can't compile code in this case, you can still use it to do image processing)

Supported resize algorithms (-i or --interpolation flag):

l3: Lanczos3 - Default
l2: Lanczos2
n: Nearest Neighbor
bc: Bicubic
bl: Bilinear
mn: Mitchell-Netravali

See here for live samples.

Hacking on Blade

Pull requests are happily accepted.

Here's what you should know if you want to improve Blade:

Your workflow starting point is the Makefile. There you should see how to setup the development tooling, run builds, tests and coverage.
The architecture splits out the runner from the converter, so that we could swap to other, faster, converters (vips) if needed.
The other concerns are the Contents.json (contents.go) parsing and dimension (dimensions.go) computation logic.
Finally, you're left with the Bladefile (bladefile.go) and CLI (main.go) logic to handle.

Also, check out fixtures for quick image catalog configuration to work with.

Here is a typical flow:

Clone project
Branch off for your changes
Edit code
Test your changes, submit PR
(release) make bump
(release) make release
(release) use hub to upload release binaries
(release) make brew_sha ver=<current version>
(release) update jondot/homebrew-tap version and sha to point to new binary

(* 'release' flows are done by core committers)

Contributing

Fork, implement, add tests, pull request, get my everlasting thanks and a respectable place here :).

Copyright

blade's People

Contributors

Stargazers

Watchers

blade's Issues

blade fatal error: fault [signal 0xb addr=0xf3201307c33 pc=0x13f732]

Hello, I have a problem with blade. I can't find the reason. If you know the question, please reply to me. Thank you
How can I get your failure status and terminate shell?

error image:

Support iMessage Extension & Sticker Pack icons

Let's support icon sizes for iMessage iMessage extensions & sticker packs.

Guidelines

Discussed under iMessage App and Sticker Pack Icons
https://developer.apple.com/ios/human-interface-guidelines/extensions/messaging/

By the time I'm writing this, it required variations in sizes:

1024px by 768px
120px by 90px
64px by 48px
180px by 135px
96px by 72px
58px by 58px
148px by 110px
87px by 87px
54px by 40px
134px by 100px
81px by 60px

Does Blade maintain directory structure in the xcassets folder?

One of the great things about Xcode's xcassets Import feature is if you import from a folder it will maintain the directory structure the images were in. Does Blade do this automatically?

iPhone and iPad Notification have not automatically generated

Xcode version 8.3.3,OS 10.12.6

I use the following command:
"blade -s icon.png -o AppIcon.appiconset -c"
AppIcon.appiconset is a empty directory.
A new Contents.json file and all size icons are automatically generated in AppIcon.appiconset directory . That's greate.
But the iPhone and iPad Notification sizes are still missing.

Then,I use the following command:
"blade -s icon.png -o AppIcon.appiconset -c -t AppIcon.appiconset/Contents.json"
Nothing happened.

But I open the Xcode project, which uses the AppIcon.appiconset above,use the following command again.
"blade -s icon.png -o AppIcon.appiconset -c -t AppIcon.appiconset/Contents.json"

The iPhone Notification and iPad Notification are both automatically generated.

Is there any way to generate all icons (especially notification) without opening Xcode project?

Blade vNext

Hi all!

I've been planning to make Blade more powerful for a long while. Since interest has been growing tremendously for this tool recently, I think that is enough motivation to kick off the next iteration of Blade. I've been requested many times to also have Android support (in addition to updating Blade to recent Apple products), and that is something I plan to have.

You can help!
Please comment below of what features you'd like to have the most.

@eralpkaraduman @Dschee @huafeng1992 @ntnmrndn @martinprot @emilwojtaszek please feel free to chime in 🥇

Incremental builds

When blade is integrated as a build script to automatically be run on each build then build times can become quite long because blade is generating all images – even if nothing has changed. Therefore it would be great if blade could detect when it has to rebuild images and otherwise just keep things as is and skip images that didn't change.

I think in order to achieve this there are several possibilities. The easiest could be that blade simply checks the last change dates of the source file and the destination file and compares those. If the destination file was last changed after the source file was changed then it could skip rebuilding the image, otherwise it would behave like now.

Alternatively blade could also generate a file (something like Bladefile.lock) which lists the date the source images were last built and check if that date is after the source images last change date and the Bladefiles last change date then it would skip the image if both cases were given.

If implemented there should also be a possibility to force rebuilding all images, something like blade --no-skip-unchanged is what I'm thinking of. We could also make it opt-in like so: blade --skip-unchanged.

What do you think? Unfortunately I can't do these changes myself since I don't speak Go (yet).

Supported input formats?

Is there a list somewhere which image formats are supported as source? For example, can I use the SVG or PDF files my artist sends me directly?

Manage existing image files

Hi @jondot

thank you for this project! This is something I've always thought about, but your current implementation is even better than my dreams :)

I see some space of possible enhancement in the way file names are handled: currently as I understand it is not possible to use wildcards, and image PNGs must be mapped 1-to-1 with imagesets in asset catalogs. I wonder if you have any thoughts on how to handle wildcards or file name pattern matching in Bladefiles. A different approach could be to auto-generate Bladefiles from the content of a folder or an asset catalog.

Cheers,
ac

it's Xcode

not XCode.

Sorry for the nitpicking :)

Add support for custom output size

It would be incredibly useful to be able to set the output resolution in points for an image, because you could store the massive full resolution files and only export low resolution images, which gives you the flexibility of later changing the export resolution as needed.

@2x or @3x

I really enjoy blade. Really like it because it's easy to create a build phase and have everything run automatically, never worry about that stuff anymore.

Though, I do have a question. When I supply an @3x image, this is what my result looks like:

As you can see, it seems that the @3x image is used as an @2x image. This can be a misunderstanding on my side, but I would expect that I have to supply the biggest possible image.

Also, I learned that it's best practice to design @1x images using vector formats. When slicing you just slice everything and than resize your canvas @2x and @3x to make sure you don't get "half pixels" with the @1x images. I know it has been suggested here, but it might be a useful addition to support one (or more vector formats). Those vector files would be the @1x images, and then automate the steps described above.