A gem to interact with Procreate .swatches
files.
This gem offers the possibility to:
- parse an existing
.swatches
color palette to an object and extract the colors in various color formats - generate a Procreate color palette from an array of colors and export it to a
.swatches
file
Behind the scenes, Procreate::Swatches
uses the Chroma gem to wrap colors and provide a better experience in interacting with colors. For more in depth use cases, consult the documentation for Chroma::Color
, available here.
Add this line to your application's Gemfile:
gem 'procreate-swatches'
And then execute:
$ bundle
Or install it yourself as:
$ gem install procreate-swatches
Before using the gem, you have to require the main file:
require 'procreate/swatches'
The gem allows you to parse an existing .swatches
file to a Procreate::Swatches::Wrapper
instance, which will allow you to further manipulate the colors.
For full documentation, refer to Procreate::Swatches::Parser documentation
Example 1
file_path = '/file/path/to/palette.swatches'
# Initialize a new instance of `Procreate::Swatches::Parser` with the file path to the `.swatches` file
parser = Procreate::Swatches::Parser.new(file_path)
# Use the method `#call` to parse the file; this will return an instance of `Procreate::Swatches::Wrapper`
wrapper = parser.call
Example 2
For ease of use, a .call
method is available:
file_path = '/file/path/to/palette.swatches'
wrapper = Procreate::Swatches::Parser.call(file_path)
Example 3
For convenience, a top-level method can be used to parse a .swatches
file
file_path = '/file/path/to/palette.swatches'
wrapper = Procreate::Swatches.parse(file_path)
# which is also aliased as `.from_file`
wrapper = Procreate::Swatches.from_file(file_path)
For full documentation, refer to Procreate::Swatches::Wrapper documentation
After successfully converting a .swatches
file to a Procreate::Swatches::Wrapper
instance, you can further interact with the palette in a Ruby way.
Using the Procreate::Swatches::Wrapper
, you can access the name and the colors array of the .swatches
file.
wrapper.name
# => "Snowy Landscape"
wrapper.colors
# => [hsv(195, 16%, 81%), hsv(288, 6%, 68%), hsv(232, 19%, 67%)]
By default, each color availabe in the colors array is an instance of Chroma::Color
By providing a format parameter to the #colors
method, you can retrieve the colors in one of the availabe formats (supported by Chroma::Color)
# converting to hex
wrapper.colors(format: :hex)
# => ["#aec6cf", "#aba3ad", "#8a8fab"]
All the availabe formats for converting colors:
wrapper.available_color_formats
# => [:hsv, :hsl, :hex, :hex8, :rgb, :name]
# the list is also available using
Procreate::Swatches::Wrapper::AVAILABLE_COLOR_FORMATS
To add a new color to the wrapper's colors array, use the push
or <<
method
wrapper.push("#aaa")
# => [hsv(195, 16%, 81%), hsv(288, 6%, 68%), hsv(232, 19%, 67%), #aaa]
wrapper << "#bbb"
# => [hsv(195, 16%, 81%), hsv(288, 6%, 68%), hsv(232, 19%, 67%), #aaa, #bbb]
This will add the color to the array (if valid) and return the colors array, including the newly-added color. Note that each color is an instance of Chroma::Color
For convenience, you can directly export a Procreate::Swatches::Wrapper instance to a .swatches
file:
wrapper.export
# => "path/to/your/palette.swatches"
# which is also aliased as
wrapper.to_file
# => "path/to/your/palette-1.swatches"
For full documentation, refer to Procreate::Swatches::Exporter documentation
You can easily export a Procreate::Swatches::Wrapper
to a .swatches
file.
Example 1
exporter = Procreate::Swatches::Exporter.new(wrapper, options)
swatches_path = export.call
# => "path/to/your/palette.swatches"
The .swatches
path is also available afterwards, using the swatches_path
attribute:
exporter.swatches_path
# => "path/to/your/palette.swatches"
Example 2
For ease of use, a .call
method is available:
swatches_path = Procreate::Swatches::Exporter.call(wrapper, options)
Example 3
For convenience, a top-level method can be used to export an array of colors to a .swatches
file:
name = 'Snowy landscape'
colors = ["#aaa", "#bbb", "#ccc"]
swatches_path = Procreate::Swatches.export(name, colors)
# => "path/to/your/snowy_landscape.swatches"
# which is also aliased as
swatches_path = Procreate::Swatches.to_file(name, colors)
# => "path/to/your/snowy_landscape-1.swatches"
The Procreate::Swatches::Exporter
class supports a number of options while exporting to a .swatches
file.
options = { export_directory: '/Users/username/Desktop' }
swatches_path = Procreate::Swatches.to_file(name, colors, options)
# => "/Users/username/Desktop/snowy_landscape.swatches"
options = {
export_directory = '/Users/username/Desktop',
file_name: 'gorgeous_palette'
}
swatches_path = Procreate::Swatches.to_file(name, colors, options)
# => "/Users/username/Desktop/gorgeous_palette.swatches"
The default values for these options are:
# The result of calling `Dir.pwd`, which returns the current working directory
export_directory = Dir.pwd
# The sanitized string of the `Procreate::Swatches::Wrapper` name
file_name = wrapper.name
These options are supported on every method that can export a .swatches
file:
Procreate::Swatches::Exporter.new(wrapper, options).call
Procreate::Swatches::Exporter.call(wrapper, options)
Procreate::Swatches.to_file(name, colors, options)
Procreate::Swatches.export(name, colors, options)
wrapper.export(options)
wrapper.to_file(options)
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/laurentzziu/procreate-swatches. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Procreate::Swatches
project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.