{"id":17436258,"url":"https://github.com/beenotung/augment-image","last_synced_at":"2026-01-22T07:33:48.816Z","repository":{"id":257825971,"uuid":"871114992","full_name":"beenotung/augment-image","owner":"beenotung","description":"Image augmentation library and cli for machine learning tasks","archived":false,"fork":false,"pushed_at":"2024-10-14T10:20:35.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-27T14:57:52.204Z","etag":null,"topics":["augmentation","blur","cli","crop","data-augmentation","flip","flipx","flipy","grayscale","image","machine-learning","rotate","scale","shear","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/augment-image","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beenotung.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-11T09:51:20.000Z","updated_at":"2024-10-14T10:20:38.000Z","dependencies_parsed_at":"2024-10-19T08:54:19.704Z","dependency_job_id":null,"html_url":"https://github.com/beenotung/augment-image","commit_stats":null,"previous_names":["beenotung/augment-image"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/beenotung/augment-image","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Faugment-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Faugment-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Faugment-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Faugment-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beenotung","download_url":"https://codeload.github.com/beenotung/augment-image/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Faugment-image/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28658107,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T01:17:37.254Z","status":"online","status_checked_at":"2026-01-22T02:00:07.137Z","response_time":144,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["augmentation","blur","cli","crop","data-augmentation","flip","flipx","flipy","grayscale","image","machine-learning","rotate","scale","shear","typescript"],"created_at":"2024-10-17T10:07:46.403Z","updated_at":"2026-01-22T07:33:48.801Z","avatar_url":"https://github.com/beenotung.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# augment-image\n\nImage augmentation library and cli for machine learning tasks\n\n[![npm Package Version](https://img.shields.io/npm/v/augment-image)](https://www.npmjs.com/package/augment-image)\n\n## Features\n\n- Rich combination of customizable image augmentation\n  - background color\n  - scale\n  - crop\n  - shear\n  - rotate\n  - gray-scale\n  - flipX\n  - flipY\n  - blur\n- Typescript support\n- Support usage from cli\n\n## Installation\n\n```bash\nnpm install augment-image\n```\n\nYou can also install `augment-image` with [pnpm](https://pnpm.io/), [yarn](https://yarnpkg.com/), or [slnpm](https://github.com/beenotung/slnpm)\n\nNote that optional dependency should not be disabled, sharp installs the os-specific native package as optional dependencies.\n\n## Usage Example\n\n**Run the cli with npx**:\n\n```shell\nnpx augment-image [options]\n```\n\n**Available options**:\n\n```\nGeneral:\n  -h, --help                  Show this help message and exit.\n  -v, --version               Show the version number and exit.\n\nConfiguration:\n  -i, --init                  Initialize a configuration file.\n\nRun Mode:\n  -r, --run                   Run the main logic of the application.\n  -s  --srcDir \u003cpath\u003e         Specify the source directory. Default is \"./images/raw\".\n  -o, --outDir \u003cpath\u003e         Specify the output directory. Default is \"./images/augments\".\n  -q, --quiet                 Disable verbose logging. By default, verbose is enabled.\n```\n\n**Notes**:\n\n- Use the --init option to generate a default config file.\n- You can edit the config in \"config.json\" in the current directory.\n- The config file must exist in the run mode.\n\n**Use as library**:\n\n```typescript\nimport {\n  aggressiveFilterGroupsOptions,\n  buildFilterGroups,\n  scanDirectory,\n} from 'augment-image'\n\nasync function main() {\n  // use custom settings\n  let filterGroups = buildFilterGroups({\n    // RGBA background will be used for out-of-range content when rotate, scale, or shear\n    background: ['#ffffffff'],\n    scale: [\n      [0.5, 0.5],\n      [1.0, 0.5],\n      [2.0, 2.0],\n    ],\n    crop: [\n      [Infinity, Infinity],\n      [100, 100],\n      [50, 50],\n    ],\n    shear: [\n      [0, 0],\n      [-8, 0],\n      [+8, 0],\n      [0, -8],\n      [0, +8],\n    ],\n    rotate: [0, 8, -8, 16, -16],\n    grayscale: 'both',\n    flipX: true,\n    blur: [0, 1, 2],\n  })\n\n  // use default settings\n  filterGroups = buildFilterGroups(aggressiveFilterGroupsOptions)\n\n  await scanDirectory({\n    srcDir: './images/raw',\n    outDir: './images/augmented',\n    filterGroups,\n    verbose: true,\n  })\n}\nmain().catch(e =\u003e console.error(e))\n```\n\n## Typescript Signature\n\n\u003cdetails\u003e\n  \u003csummary\u003ecore functions and types\u003c/summary\u003e\n\n```typescript\nimport { Sharp } from 'sharp'\n\n/** @description the core function that apply all combination of image augmentation filters */\nexport function augmentImage(\n  image: Sharp,\n  filterGroups: FilterGroup[],\n): AsyncGenerator\u003cSharp, void, unknown\u003e\n\n/** @description scan images in `srcDir` and save the augmented images in `outDir` */\nexport function scanDirectory(options: {\n  srcDir: string\n  outDir: string\n  filterGroups: FilterGroup[]\n  /** @description default `true` */\n  verbose?: boolean\n}): Promise\u003c{\n  fileCount: number\n}\u003e\n\n/** @description generate filter groups with variants based on the given options */\nexport function buildFilterGroups(\n  options: BuildFilterGroupsOptions,\n): FilterGroup[]\n\nexport type BuildFilterGroupsOptions = {\n  /**\n   * @description for region that overflow when transform\n   * default `['#00000000']`\n   */\n  background?: string[]\n  /**\n   * @description `Array\u003c[w,h]\u003e` in percentage, applied before crop\n   * e.g. `[[0.8,1.2]]` for 80% in width and 120% in height\n   * */\n  scale?: [w: number, h: number][]\n  /**\n   * @description `Array\u003c[w,h]\u003e` in pixel unit, applied before after scale\n   * e.g. `[[100,100],[100,150],[150,100]]`\n   */\n  crop?: [w: number, h: number][]\n  /**\n   * @description `Array\u003c[x,y]\u003e` in degree, applied after crop\n   * e.g. `[[0,0],[-16,0],[+16,0],[0,-16],[0,+16]]`\n   * */\n  shear?: [x: number, y: number][]\n  /**\n   * @description in degree\n   * e.g. `[-15, 0, 15]`\n   * */\n  rotate?: number[]\n  grayscale?: 'always' | 'never' | 'both'\n  flipX?: boolean\n  flipY?: boolean\n  /**\n   * @description sigma range from 0 to 1000\n   * e.g. `[0, 1]`\n   * */\n  blur?: number[]\n}\n\n/** @description a reference setting that balance the number of image augmentation combination and the time cost */\nexport let aggressiveFilterGroupsOptions: BuildFilterGroupsOptions\n\ntype FilterGroup = {\n  name: string\n  variants: Filter[]\n}\n\ntype Filter = {\n  (image: Sharp): Sharp[] | Sharp | Promise\u003cSharp[] | Sharp\u003e\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003ehelper functions\u003c/summary\u003e\n\n```typescript\nimport { Sharp } from 'sharp'\n\n/** @description generate sequence of `number[]` */\nexport function range(args: {\n  /** @description inclusive */\n  from: number\n  /** @description inclusive */\n  to: number\n  /** @description can be positive or negative */\n  step: number\n}): number[]\n\n/** @description generate sequence of `number[]` */\nexport function rangeAround(args: {\n  center: number\n  /** @description inclusive */\n  range: number\n  /** @description can be positive or negative */\n  step: number\n}): number[]\n\n/** @description generate `[[a,a],[b,b]]` into combination of `[[a,a],[a,b],[b,a],[b,b]]` */\nexport function expandCropSize(\n  /** @description e.g. `[Infinity, 1000, 500, 300, 200, 100, 50]` */\n  size: number[],\n): number[][]\n```\n\n\u003c/details\u003e\n\n## License\n\nThis project is licensed with [BSD-2-Clause](./LICENSE)\n\nThis is free, libre, and open-source software. It comes down to four essential freedoms [[ref]](https://seirdy.one/2021/01/27/whatsapp-and-the-domestication-of-users.html#fnref:2):\n\n- The freedom to run the program as you wish, for any purpose\n- The freedom to study how the program works, and change it so it does your computing as you wish\n- The freedom to redistribute copies so you can help others\n- The freedom to distribute copies of your modified versions to others\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeenotung%2Faugment-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeenotung%2Faugment-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeenotung%2Faugment-image/lists"}