Add asset transformation sample (#2267)

This adds a sample Flutter project that demonstrates a
soon-to-be-released feature, asset transformation[^1]. [PR for
flutter.dev
documentation](https://github.com/flutter/website/pull/10471).

This feature isn't the easiest to explain using documentation, so I
think augmenting that documentation with a sample is appropriate.

This sample demonstrates 1) how to use an existing Dart package (that is
compatible with the feature) as an asset transformer and 2) how to write
a Dart package that is compatible with this feature. This should be
clear from the README.md.

**Advice for reviewing this PR.** The goal here is that most users that
read the documentation and follow the link from there to this sample
should be able to figure out what the feature does and how to use it.
Try to imagine yourself in this position and follow this story. If the
feature is still unclear, then there is probably something we can do to
improve this sample or the docs. Said more simply, follow these steps:
1) Start at the new section to be added to Flutter.dev
(https://flutter-docs-prod--pr10471-document-asset-transformers-cc21qf01.web.app/ui/assets/assets-and-images#automatic-transformation-of-asset-files-at-build-time).
It should naturally link you to the sample project. Start with the
README and see if things make sense.

## Pre-launch Checklist

- [X] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [X] I signed the [CLA].
- [X] I read the [Contributors Guide].
- [X] I updated/added relevant documentation (doc comments with `///`).
- [X] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].

<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo
[CLA]: https://cla.developers.google.com/
[Discord]: https://github.com/flutter/flutter/wiki/Chat
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md

[^1]: If you are super curious about this feature, see [the tracking
issue for its
implementation](https://github.com/flutter/flutter/issues/143348).

---------

Co-authored-by: Eric Windmill <eric@ericwindmill.com>

asset_transformation/grayscale_transformer/.gitignore

@@ -0,0 +1,3 @@
+# https://dart.dev/guides/libraries/private-files
+# Created by `dart pub`
+.dart_tool/

asset_transformation/grayscale_transformer/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0
+
+- Initial version.

asset_transformation/grayscale_transformer/analysis_options.yaml

@@ -0,0 +1,30 @@
+# This file configures the static analysis results for your project (errors,
+# warnings, and lints).
+#
+# This enables the 'recommended' set of lints from `package:lints`.
+# This set helps identify many issues that may lead to problems when running
+# or consuming Dart code, and enforces writing Dart using a single, idiomatic
+# style and format.
+#
+# If you want a smaller set of lints you can change this to specify
+# 'package:lints/core.yaml'. These are just the most critical lints
+# (the recommended set includes the core lints).
+# The core lints are also what is used by pub.dev for scoring packages.
+
+include: package:lints/recommended.yaml
+
+# Uncomment the following section to specify additional rules.
+
+# linter:
+#   rules:
+#     - camel_case_types
+
+# analyzer:
+#   exclude:
+#     - path/to/excluded/files/**
+
+# For more information about the core and recommended set of lints, see
+# https://dart.dev/go/core-lints
+
+# For additional information about configuring this file, see
+# https://dart.dev/guides/language/analysis-options

asset_transformation/grayscale_transformer/bin/grayscale_transformer.dart

@@ -0,0 +1,36 @@
+import 'dart:io';
+
+import 'package:args/args.dart';
+import 'package:image/image.dart';
+
+const inputOptionName = 'input';
+const outputOptionName = 'output';
+
+int main(List<String> arguments) {
+  // The flutter tool will invoke this program with two arguments, one for
+  // the `--input` option and one for the `--output` option.
+  // `--input` is the original asset file that this program should transform.
+  // `--output` is where flutter expects the transformation output to be written to.
+  final parser = ArgParser()
+    ..addOption(inputOptionName, mandatory: true, abbr: 'i')
+    ..addOption(outputOptionName, mandatory: true, abbr: 'o');
+
+  ArgResults argResults = parser.parse(arguments);
+  final String inputFilePath = argResults[inputOptionName];
+  final String outputFilePath = argResults[outputOptionName];
+
+  try {
+    final Image image = decodeImage(File(inputFilePath).readAsBytesSync())!;
+    final Image imageInGrayscale = grayscale(image);
+    File(outputFilePath).writeAsBytesSync(encodeJpg(imageInGrayscale));
+
+    return 0;
+  } catch (e) {
+    // The flutter command line tool will see a non-zero exit code (1 in this case)
+    // and fail the build. Anything written to stderr by the asset transformer
+    // will be surfaced by flutter.
+    stderr.writeln('Unexpected exception when producing grayscale image.\n'
+        'Details: $e');
+    return 1;
+  }
+}

asset_transformation/grayscale_transformer/pubspec.yaml

@@ -0,0 +1,14 @@
+name: grayscale_transformer
+description: A sample command-line application.
+version: 1.0.0
+
+environment:
+  sdk: ^3.3.1
+
+dependencies:
+  args: ^2.4.2
+  image: ^4.1.7
+
+dev_dependencies:
+  lints: ^3.0.0
+  test: ^1.24.0