{"id":15038620,"url":"https://github.com/brightdigit/assetlib","last_synced_at":"2025-04-09T23:53:05.192Z","repository":{"id":40451657,"uuid":"236527662","full_name":"brightdigit/AssetLib","owner":"brightdigit","description":"Build and Parse Asset Catalogs in Swift.","archived":false,"fork":false,"pushed_at":"2025-02-26T13:08:31.000Z","size":431,"stargazers_count":9,"open_issues_count":6,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T23:52:51.314Z","etag":null,"topics":["app-icon-generator","app-icons","appiconset","image-set","macos","parse-asset-catalogs","swift","watchos"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brightdigit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-27T15:51:22.000Z","updated_at":"2025-02-26T13:07:58.000Z","dependencies_parsed_at":"2022-08-09T20:51:15.673Z","dependency_job_id":null,"html_url":"https://github.com/brightdigit/AssetLib","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brightdigit%2FAssetLib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brightdigit%2FAssetLib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brightdigit%2FAssetLib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brightdigit%2FAssetLib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brightdigit","download_url":"https://codeload.github.com/brightdigit/AssetLib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131454,"owners_count":21052819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app-icon-generator","app-icons","appiconset","image-set","macos","parse-asset-catalogs","swift","watchos"],"created_at":"2024-09-24T20:39:17.869Z","updated_at":"2025-04-09T23:53:05.172Z","avatar_url":"https://github.com/brightdigit.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Logo](https://raw.githubusercontent.com/brightdigit/AssetLib/master/logo.png)\n\n# AssetLib\n\n[![SwiftPM](https://img.shields.io/badge/SPM-Linux%20%7C%20iOS%20%7C%20macOS%20%7C%20watchOS%20%7C%20tvOS-success?logo=swift)](https://swift.org)\n[![Twitter](https://img.shields.io/badge/twitter-@brightdigit-blue.svg?style=flat)](http://twitter.com/brightdigit)\n[![GitHub](https://img.shields.io/github/license/brightdigit/AssetLib)](https://github.com/brightdigit/AssetLib/blob/master/LICENSE)\n[![GitHub issues](https://img.shields.io/github/issues/brightdigit/AssetLib)](https://img.shields.io/github/issues/brightdigit/AssetLib)\n\n[![actions](https://github.com/brightdigit/AssetLib/actions/workflows/assetlib.yml/badge.svg)](https://github.com/brightdigit/AssetLib/actions/workflows/assetlib.yml)\n[![CircleCI](https://img.shields.io/circleci/build/github/brightdigit/AssetLib?label=xenial\u0026logo=circleci\u0026token=9a2a5fd57594c2138187c14307c4b84e5f696d4d)](https://circleci.com/gh/brightdigit/AssetLib)\n[![Bitrise](https://img.shields.io/bitrise/96bc7c2338f588b6?label=macOS\u0026logo=bitrise\u0026token=JQwTk_9aG8HJcafb-Sqwbw)](https://app.bitrise.io/app/96bc7c2338f588b6)\n\n[![Codecov](https://img.shields.io/codecov/c/github/brightdigit/AssetLib)](https://codecov.io/gh/brightdigit/AssetLib)\n[![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/brightdigit/AssetLib)](https://www.codefactor.io/repository/github/brightdigit/AssetLib)\n[![codebeat badge](https://codebeat.co/badges/4f86fb90-f8de-40c5-ab63-e6069cde5002)](https://codebeat.co/projects/github-com-brightdigit-assetlib-master)\n[![Code Climate maintainability](https://img.shields.io/codeclimate/maintainability/brightdigit/AssetLib)](https://codeclimate.com/github/brightdigit/AssetLib)\n[![Code Climate technical debt](https://img.shields.io/codeclimate/tech-debt/brightdigit/AssetLib?label=debt)](https://codeclimate.com/github/brightdigit/AssetLib)\n[![Code Climate issues](https://img.shields.io/codeclimate/issues/brightdigit/AssetLib)](https://codeclimate.com/github/brightdigit/AssetLib)\n\n[![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)\n\n\n\u003e Build, Create, and Modify Asset Catalogs in Swift or in the Terminal\n\n## Features\n\nIncluded with this library is the ability:\n\n- [x] Programmatically parse and modify Asset Catalogs\n- [x] Create Asset Catalogs based on Template in code or terminal\n\n## Reqirements\n\n- iOS 9.0+ / macOS 10.10+ / tvOS 9.0+ / watchOS 2.0+ / Linux \n- Xcode 11.4+\n- Swift 5.2+\n\n## Installing \n\n\n### Swift Package Manager\n\nThe [Swift Package Manager](https://swift.org/package-manager/) is a tool for automating the distribution of Swift code and is integrated into the `swift` compiler. AssetLib does support its use on supported platforms.\n\nOnce you have your Swift package set up, adding AssetLib as a dependency is as easy as adding it to the `dependencies` value of your `Package.swift`.\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/brightdigit/AssetLib.git\", .upToNextMajor(from: \"0.1.0\"))\n]\n```\n\n## Usage\n\n### [API Documentation](/Documentation/Reference/README.md)\n\n### Asset Catalog Items (i.e. App Icons and Image Sets)\n\n**AssetLib** contains a type `AssetSpecificationDocument` which can both be constructed, decoded, encoded and more. Typically in Xcode Asset Catalogs, this would be the `Contents.json` file inside an Image set or App Icon set. Therefore to read an `AssetSpecificationDocument`:\n\n```swift\n// read the \"Contents.json\" for either Image Set or App Icon\nlet dirURL = let outputDirURL = URL(fileURLWithPath: \"ImageSet.imageset\", isDirectory: true)\nlet url = dirURL.appendingPathComponent(\"Contents.json\")\n\nlet decoder = JSONDecoder()\nlet data = try Data(contentsOf: url)\nlet document = decoder.decode(AssetSpecificationDocument.self, from: data)\n```\n\n`AssetSpecificationDocument` contains three properties: `info`, `properties`, and `images`. The `images` property contains the specifications for each image used in the Image set or App Icon.\n\n#### Asset Catalog Images \n\n**AssetLib** contains a type `AssetSpecification` for each image in a `AssetSpecificationDocument`. This could be anything from a 2x image in an Image Set to the image for an iPad notification.\n\nIn order to build or modify an `AssetSpecification` use the `AssetSpecificationBuilder` type:\n\n```swift\n...\nlet document = decoder.decode(AssetSpecificationDocument.self, from: data)\nlet newImages = document.images.map {\n  oldImage in\n  var builder = AssetSpecificationBuilder(specifications: oldImage)\n  builder.locale = Locale(identifier: \"fr\")\n  return builder.assetSpec()\n}\nlet modifiedDocument = AssetSpecificationDocument(\n  info: document.info,\n  images: newImages,\n  properties: document.properties)\n```\n\n#### Saving Your Document\n\nIn order to save your new `AssetSpecificationDocument`, simply use `JSONEncoder`:\n\n```swift\n// save to \"Contents.json\" for either Image Set or App Icon to work in Xcode\nlet outputDirURL = let outputDirURL = URL(fileURLWithPath: \"NewImageSet.imageset\", isDirectory: true)\nlet outputURL = outputDirURL.appendingPathComponent(\"Contents.json\")\n\n// In order to have it look similar to how Xcode outputs the document\nlet encoder = JSONEncoder()\nencoder.outputFormatting = [.prettyPrinted]\n\nlet data = try encoder.encode(modifiedDocument)\ntry data.write(to: outputURL)\n```\n\n### Templating\n\nYou can build an App Icon for an Asset Catalog based on a template either programmatically or in the terminal. \n\n#### App Icons\n\nIn order to create an `AssetSpecificationDocument`, create an `AppIconTemplate` with the settings of your choice as well as a `AppIconTemplateBuilder`. Then call: `.document(fromTemplate:)` to build the `AssetSpecificationDocument`:\n\n```swift\nlet template = AppIconTemplate(\n  devices: [.car, .ipad, .iphone, .mac, .tv, .watch], \n  specifyGamut: true, \n  prerendered: true)\nlet builder = AppIconTemplateBuilder()\nlet document = builder.document(fromTemplate: template)\n```\n\n`AppIconTemplate` has three properties which correspond with the properties in available in **Xcode**:\n\n- `devices`: _optional_ `Set\u003cAppIconDevice\u003e` the devices which this AppIcon supports, which are: `.car`, `.ipad`, `.iphone`, `.mac`, `.tv`, `.watch`. If `nil`, assume **all** devices are supported.\n- `specifyGamut`: _optional, default: false_ whether to specify separate images for sRGB and the P3 wide gamut color space.\n-  `prerendered` : _optional, default: false_ backward compatibile property for iOS 6.0 indicating if the icon includes the mask and shine effect\n\nFor more details, check out the documentation on `AppIconTemplate`.\n\n#### Image Sets\n\nIn order to create an `AssetSpecificationDocument`, create an `ImageSetTemplate` with the settings of your choice as well as a `ImageSetTemplateBuilder`. Then call: `.document(fromTemplate:)` to build the `AssetSpecificationDocument`:\n\n```swift\nlet template = ImageSetTemplate(\n  renderAs: .template,\n  compression: .gpuOptimizedBest,\n  preserveVectorData: true,\n  devices: Set([.universal]),\n  appearances: [\n    ValuedAppearance(value: Luminosity.light).eraseToAny(), \n    ValuedAppearance(value: Luminosity.dark).eraseToAny()\n  ],\n  scaling: .single,\n  specifyGamut: true,\n  direction: [],\n  specifiedWidthClass: nil,\n  specifiedHeightClass: nil,\n  memorySet: [],\n  graphicFSSet: [],\n  specifyAWWidth: false,\n  autoScaling: false,\n  locales: [],\n  resourceTags: []\n)\nlet builder = ImageSetTemplateBuilder()\nlet document = builder.document(fromTemplate: template)\n```\n\nFor more details, check out the documentation on `ImageSetTemplate`.\n\n#### Command Line Application\n\nIn addition to the API, you can build an `AssetSpecificationDocument` i.e. Contents.json file using the executable provided in the Swift package:\n\n```\nUSAGE: assetlibrary \u003ctemplate-file\u003e \u003coutput\u003e\n\nARGUMENTS:\n  \u003ctemplate-file\u003e         JSON template file. \n  \u003coutput\u003e                Output directory or file. If this path ends in either\n                          'imageset' or 'appicon', then a directory will be\n                          created with a 'Contents.json' file inside.\n                          Otherwise, it will be the resulting file path. \n\nOPTIONS:\n  -h, --help              Show help information.\n```\n\nSimply create a `json` file, with the corresponding properties for a the `ImageSetTemplate` or `AppIconTemplate`. The corresponding JSON properties for each property in Swift are:\n\n| Template Type | Swift Name | JSON Name |\n|---------------|--------------|---------------|\n| AppIcon | devices | devices |\n| AppIcon | specifyGamut | specify-gamut |\n| AppIcon | prerendered | pre-rendered |\n| ImageSet | templateRenderingIntent | template-rendering-intent |\n| ImageSet | compressionType | compression-type |\n| ImageSet | preservesVectorRepresentation | preserves-vector-representati |\n| ImageSet | devices | devices |\n| ImageSet | appearances | appearances |\n| ImageSet | scaling | scaling |\n| ImageSet | displayGamuts | display-gamuts |\n| ImageSet | languageDirections | language-directions |\n| ImageSet | widthClass | width-class |\n| ImageSet | heightClass | height-class |\n| ImageSet | memorySet | memory-set |\n| ImageSet | graphicsFeatureSets | graphics-feature-sets |\n| ImageSet | appleWatchScreens | apple-watch-screens |\n| ImageSet | autoScaling | auto-scaling |\n| ImageSet | locales | locales |\n| ImageSet | onDemandResourceTags | on-demand-resource-tags |\n\n##### Examples\n\n###### Image Set\n\n- for a template image\n- with a specific dark mode\n- support for english, spanish, and french\n- individual images for each Apple Watch size\n\n\n**imageset-template.json**\n\n```json\n{\n  \"template-rendering-intent\" : \"template\",\n  \"appearances\" : [\n    {\n      \"appearance\" : \"luminosity\",\n      \"value\" : \"dark\"\n    }\n  ],\n  \"appleWatchScreens\" : true,\n  \"locales\" : [\"en\", \"es\", \"fr\"]\n}\n```\n\n**usage**\n\n```bash\n$ assetlibrary Example/Templates/imageset-template.json Example/Templates/Assets.xcassets/Template.imageset\n```\n\n###### iPhone and iPad App Icon\n\n**appicon-iOS.json**\n\n```json\n{\n  \"devices\" : [\"iphone\", \"ipad\"]\n}\n```\n\n**usage**\n\n```bash\n$ assetlibrary Example/Templates/appicon-iOS.json Example/Templates/Assets.xcassets/AppIcon.appiconset\n```\n\n###### Multi-Device Image Set (w/ Display Gamuts)\n\n**appicon-gamut.json**\n\n```json\n{\n  \"specify-gamut\" : true\n}\n```\n\n**usage**\n\n```bash\n$ assetlibrary Example/Templates/appicon-gamut.json Example/Templates/Assets.xcassets/Gamut.appiconset\n```\n\n###### Multi-Device Image Set (w/o CarPlay)\n\n**appicon-devices.json**\n\n```json\n{\n  \"devices\" : [\"watch\", \"iphone\", \"ipad\", \"mac\", \"tv\"]\n}\n```\n\n**usage**\n\n```bash\n$ assetlibrary Example/Templates/appicon-devices.json Example/Templates/Assets.xcassets/Devices.appiconset\n```\n\n## Links\n\n- Asset Catalog Format Overview\n  - https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_ref-Asset_Catalog_Format/\n- Asset Catalog Image Set Documentation\n  - https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_ref-Asset_Catalog_Format/ImageSetType.html#//apple_ref/doc/uid/TP40015170-CH25-SW33\n- Asset Catalog App Icon Documentation\n  - https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_ref-Asset_Catalog_Format/AppIconType.html#//apple_ref/doc/uid/TP40015170-CH22-SW1\n\n## License\n\nAssetLib is released under the MIT license. [See LICENSE](https://github.com/brightdigit/AssetLib/blob/master/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrightdigit%2Fassetlib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrightdigit%2Fassetlib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrightdigit%2Fassetlib/lists"}