@@ -43,15 +43,175 @@ MediaPipe coding style.
4343
4444#### License
4545
46- Include a license at the top of new files .
46+ Include the Flutter license at the top of each new file you create .
4747
48- TODO: Examples
48+ ## Developing the plugins
4949
50- #### Coding styles for various languages
50+ ### Non-Dart code pre-work
5151
52- * [ Google C++ Style Guide] ( https://google.github.io/styleguide/cppguide.html ) .
53- * [ Google Python Style Guide] ( https://google.github.io/styleguide/pyguide.html )
54- * [ Google Java Style Guide] ( https://google.github.io/styleguide/javaguide.html )
55- * [ Google JavaScript Style Guide] ( https://google.github.io/styleguide/jsguide.html )
56- * [ Google Shell Style Guide] ( https://google.github.io/styleguide/shell.xml )
57- * [ Google Objective-C Style Guide] ( https://google.github.io/styleguide/objcguide.html )
52+ > Note: For now, because ` google/flutter-mediapipe ` uses a Flutter experiment, and
53+ > Flutter experiments are only available on the ` master ` channel, development or
54+ > use of any plugins found in this repository is only possible on the ` master `
55+ > channel. This restriction will be listed when the ` native-assets ` experiment
56+ > is added to the stable channel.
57+
58+ As described above, switch to the ` master ` channel to work on or use the various
59+ ` flutter-mediapipe ` plugins:
60+
61+ ``` sh
62+ $ flutter channel master
63+ $ flutter doctor
64+ ```
65+
66+ #### Checking out the ` google/mediapipe ` repository
67+
68+ Some of ` google/flutter-mediapipe ` repository's tooling requires a local checkout
69+ of the ` google/mediapipe ` repository. By default, this tooling assumes both
70+ repositories are colocated within the same directory, but if you prefer to
71+ checkout the ` google/mediapipe ` repository elsewhere, then you can specify its
72+ absolute path on your machine via the ` --source ` or ` -s ` flag.
73+
74+ #### Updating header files
75+
76+ The reason a local checkout of ` google/mediapipe ` is required is that
77+ ` google/flutter-mediapipe ` uses copies of header files found in the former. To
78+ sync the latest versions of all header files from ` google/mediapipe ` to
79+ ` google/flutter-mediapipe ` , run the ` sync_headers ` command found in the ` tool `
80+ directory like so:
81+
82+ ``` sh
83+ $ cd tool/builder && dart bin/main.dart headers
84+ ```
85+
86+ Alternatively, users of POSIX systems can use the shortcut found in the ` Makefile ` :
87+
88+ ``` sh
89+ $ make headers
90+ ```
91+
92+ #### Adding new header files
93+
94+ If you are adding new tasks, it is highly likely you will need to include new headers
95+ in the sweep executed by the ` sync_headers ` command. To do this, open
96+ ` tool/builder/lib/sync_headers.dart ` and review the directives collected in the
97+ ` headerPaths ` variable. Add any new paths you need to collect, and then modify any
98+ relative import paths using the ` relativeIncludes ` method if necessary. It is also
99+ possible that ` relativeIncludes ` is not sufficient for all scenarios that the
100+ MediaPipe library will ever encounter, so do not hesitate to modify ` relativeIncludes `
101+ or add a new function if necessary.
102+
103+ Once you have modified this script, re-run the headers command to pull your new files
104+ out of ` google/mediapipe ` and into ` google/flutter-mediapipe ` . Pre-existing header
105+ files should not have any changes, but your new files should appear.
106+
107+ If pre-existing header files do change because they have genuinely evolved within
108+ ` google/mediapipe ` since anyone else last ran the command, those changes should be
109+ resolved within their own PR.
110+
111+ #### Running ffigen
112+
113+ Any time the header file definitions change, ` ffigen ` must be re-run for that plugin.
114+ To do this, open the ` ffigen.yaml ` file within a given plugin and ensure list of
115+ blob paths at ` headers/entry-points ` includes any new header files you have added.
116+ Then, re-run ` ffigen ` like so:
117+
118+ ``` sh
119+ $ cd packages/< pkg-name> && dart run ffigen --config=ffigen.yaml
120+ ```
121+
122+ Alternatively, users of POSIX systems can use the shortcut found in the ` Makefile ` :
123+
124+ ``` sh
125+ $ make generate_< pkg-suffix>
126+ ```
127+
128+ Consult the ` Makefile ` for the appropriate command for your plugin, or add one
129+ if you are contributing the first header files for a given plugin.
130+
131+ #### Updating the MediaPipe SDKs
132+
133+ > Note: This task can only be run from a Googler's corp laptop with LIST read
134+ > permissions on the MediaPipe bucket in Google Cloud Storage. Non-Googlers should
135+ > not encounter a need to run the command, but if you believe you have, file an issue.
136+
137+ Flutter collects MediaPipe artifacts and at build time and compiles them into your
138+ binary using the experimental new feature, named "Native Assets".
139+
140+ > Note: As described above, this feature is only available on the ` master ` channel
141+ > (as experiments in general are only available on the ` master ` channel).
142+
143+ The locations of the latest MediaPipe SDK binaries for each task are stored in the
144+ ` sdk_downloads.dart ` manifest files for each package. If you need to test against
145+ different versions of an SDK but cannot run the command, you can manually edit the
146+ ` sdk_downloads.dart ` file, though these manual edits should not be committed.
147+
148+ Finally, if you are a Googler and able to run the command, you can update each
149+ plugin's manifest file in one maneuver by running the command:
150+
151+ ``` sh
152+ $ cd tool/builder && dart bin/main.dart sdks
153+ ```
154+
155+ Alternatively, users of POSIX systems can use the shortcut found in the ` Makefile ` :
156+
157+ ``` sh
158+ $ make sdks
159+ ```
160+
161+ You do not need to take any manual steps to download or include an SDK at build-
162+ time, as the ` $ flutter run|build ` command handles that for you.
163+
164+ ### Write your Dart code
165+
166+ It is finally time to write some Dart code!
167+
168+ #### Adding a new task
169+
170+ ##### Adding the IO implementation
171+
172+ If you are contributing a new task, you should have added new header files to the
173+ ` sync_headers.dart ` script and run the command yourself. This should have copied
174+ those specified headers out of ` google/mediapipe ` and into your git clone of
175+ ` google/flutter-mediapipe ` . To begin implementing your new MediaPipe task, add
176+ a new folder to the appropriate ` <pkg_name>/lib/src/interface/tasks/ ` directory and
177+ add apporpriate exports to the ` tasks.dart ` barrel file. Then add abstract
178+ definitions for any structs newly introduced to the repository through the new
179+ task you are adding. For reference on how these interface definitions should look,
180+ consult existing interface definitions from other tasks, or from ` mediapipe_core ` .
181+
182+ Next, add concrete implementations for this task by adding an appropriate folder
183+ to the ` <pkg_name>/lib/src/io/tasks/ ` directory and appropriate exports to the
184+ ` tasks.dart ` barrel file. Your task's ` Options ` class will typically originate
185+ from Dart code, and so should know how to allocate itself into native memory and
186+ then later deallocate that memory. Most other classes originate within native
187+ memory itself and are returned to Dart by calling the task's methods. These classes
188+ should have ` .native() ` factory constructors which accept a pointer and hydrate
189+ private fields. They should also have direct constructors which accept pure Dart
190+ values and are only suitable for testing. Reference other task's implementations
191+ for inspiration on how to handle this memory management.
192+
193+ ##### Adding the web implementation
194+
195+ Next, if your task has a web folder with contents, add a web implementation. As
196+ of this writing, no web implementations yet exist.
197+
198+ ##### Adding the sample
199+
200+ New task implementations should include a new screen in the example app. Add a
201+ new element to the ` PageView ` 's children, then add your sample within that widget.
202+ For reference on how to initialize the MediaPipe SDK for your task, consult existing
203+ examples. It is recommended that you use this example as the primary way of proving
204+ to yourself that your new task implementation works as intended.
205+
206+ #### Improving an existing task
207+
208+ If you are improving an existing task, either by adding overlooked functionality
209+ or fixing a bug, your task should be much simpler than that of adding an entirely
210+ new task. If you get stuck, open a PR with everything you have accomplished and
211+ request assistance from Craig Labenz.
212+
213+ #### Adding tests
214+
215+ All new PRs should include tests that demonstrate correctness. Integration tests
216+ are demonstrated by the ` mediapipe_text ` plugin, but as of this writing, are not
217+ implemented in the ` mediapipe_genai ` plugin.
0 commit comments