Skip to content

Commit 33abadb

Browse files
de-codede-code
authored
improved cli docs (#77)
* show cli default values * document inputs and outputs * move video extra above image * using external examples to make commands runnable * added example video * introduce mask alpha earlier * added more example images * added links to used libraries * added missing background source link
1 parent f4b678a commit 33abadb

2 files changed

Lines changed: 133 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 127 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -29,11 +29,11 @@ when using this project as a library:
2929

3030
| extra name | description
3131
| ---------- | -----------
32-
| tf | TensorFlow (required). But you may use your own build.
33-
| tfjs | TensorFlow JS Model support
34-
| image | Image loading via Pillow, required by the CLI.
35-
| webcam | Webcam support via OpenCV and pyfakewebcam
36-
| video | Video support via OpenCV
32+
| tf | [TensorFlow](https://pypi.org/project/tensorflow/) (required). But you may use your own build.
33+
| tfjs | TensorFlow JS Model support, using [tfjs-graph-converter](https://pypi.org/project/tfjs-graph-converter/)
34+
| image | Image loading via [Pillow](https://pypi.org/project/Pillow/), required by the CLI.
35+
| video | Video support via [OpenCV](https://pypi.org/project/opencv-python/)
36+
| webcam | Webcam support via [OpenCV](https://pypi.org/project/opencv-python/) and [pyfakewebcam](https://pypi.org/project/pyfakewebcam/)
3737
| all | All of the libraries
3838

3939
## Python API
@@ -90,42 +90,93 @@ Those URLs can be passed as the `--model-path` arguments below, or to the `downl
9090

9191
The CLI will download and cache the model from the provided path. If no `--model-path` is provided, it will use a default model (mobilenet).
9292

93+
### Inputs and Outputs
94+
95+
Most commands will work with inputs (source) and outputs.
96+
97+
The source path can be specified via the `--source` parameter.
98+
99+
The following inputs are supported:
100+
101+
| type | description |
102+
| -----| ----------- |
103+
| image | Static image (e.g. `.png`) |
104+
| video | Video (e.g. `.mp4`) |
105+
| webcam | Linux Webcam (`/dev/videoN` or `webcam:0`) |
106+
107+
If the source path points to an external file (e.g. `https://`), then it will be downloaded and locally cached.
108+
109+
The output path can be specified via `--output`, unless `--show-output` is used.
110+
111+
The following outpus are supported:
112+
113+
| type | description |
114+
| -----| ----------- |
115+
| image_writer | Write to a static image (e.g. `.png`) |
116+
| v4l2 | Linux Virtual Webcam (`/dev/videoN`) |
117+
| window | Display a window (by using `--show-output`) |
118+
93119
### Example commands
94120

95121
#### Creating a simple body mask
96122

97123
```bash
98124
python -m tf_bodypix \
99125
draw-mask \
100-
--source /path/to/input-image.jpg \
101-
--output /path/to/output-mask.jpg \
126+
--source \
127+
"https://www.dropbox.com/s/7tsaqgdp149d8aj/serious-black-businesswoman-sitting-at-desk-in-office-5669603.jpg?dl=1" \
128+
--show-output \
102129
--threshold=0.75
103130
```
104131

132+
Image Source: [Serious black businesswoman sitting at desk in office](https://www.pexels.com/photo/serious-black-businesswoman-sitting-at-desk-in-office-5669603/)
133+
134+
#### Add the mask over the original image using `--mask-alpha`
135+
136+
```bash
137+
python -m tf_bodypix \
138+
draw-mask \
139+
--source \
140+
"https://www.dropbox.com/s/7tsaqgdp149d8aj/serious-black-businesswoman-sitting-at-desk-in-office-5669603.jpg?dl=1" \
141+
--show-output \
142+
--threshold=0.75 \
143+
--mask-alpha=0.5
144+
```
145+
146+
Image Source: [Serious black businesswoman sitting at desk in office](https://www.pexels.com/photo/serious-black-businesswoman-sitting-at-desk-in-office-5669603/)
147+
105148
#### Colorize the body mask depending on the body part
106149

107150
```bash
108151
python -m tf_bodypix \
109152
draw-mask \
110-
--source /path/to/input-image.jpg \
111-
--output /path/to/output-colored-mask.jpg \
153+
--source \
154+
"https://www.dropbox.com/s/7tsaqgdp149d8aj/serious-black-businesswoman-sitting-at-desk-in-office-5669603.jpg?dl=1" \
155+
--show-output \
112156
--threshold=0.75 \
157+
--mask-alpha=0.5 \
113158
--colored
114159
```
115160

161+
Image Source: [Serious black businesswoman sitting at desk in office](https://www.pexels.com/photo/serious-black-businesswoman-sitting-at-desk-in-office-5669603/)
162+
116163
#### Additionally select the body parts
117164

118165
```bash
119166
python -m tf_bodypix \
120167
draw-mask \
121-
--source /path/to/input-image.jpg \
122-
--output /path/to/output-colored-mask.jpg \
168+
--source \
169+
"https://www.dropbox.com/s/7tsaqgdp149d8aj/serious-black-businesswoman-sitting-at-desk-in-office-5669603.jpg?dl=1" \
170+
--show-output \
123171
--threshold=0.75 \
172+
--mask-alpha=0.5 \
124173
--parts left_face right_face \
125174
--colored
126175
```
127176

128-
#### Render a Video, while adding mask overlay, showing the result in an image
177+
Image Source: [Serious black businesswoman sitting at desk in office](https://www.pexels.com/photo/serious-black-businesswoman-sitting-at-desk-in-office-5669603/)
178+
179+
#### Add mask overlay to a video
129180

130181
```bash
131182
python -m tf_bodypix \
@@ -140,7 +191,40 @@ python -m tf_bodypix \
140191

141192
Video Source: [Video Of A Man Laughing And Happy](https://www.pexels.com/video/video-of-a-man-laughing-and-happy-1608393/)
142193

143-
#### Capture Webcam and adding mask overlay, showing the result in an image
194+
#### Blur background of a video
195+
196+
```bash
197+
python -m tf_bodypix \
198+
blur-background \
199+
--source \
200+
"https://www.dropbox.com/s/s7jga3f0dreavlb/video-of-a-man-laughing-and-happy-1608393-360p.mp4?dl=1" \
201+
--show-output \
202+
--threshold=0.75 \
203+
--mask-blur=5 \
204+
--background-blur=20
205+
```
206+
207+
Video Source: [Video Of A Man Laughing And Happy](https://www.pexels.com/video/video-of-a-man-laughing-and-happy-1608393/)
208+
209+
#### Replace the background of a video
210+
211+
```bash
212+
python -m tf_bodypix \
213+
replace-background \
214+
--source \
215+
"https://www.dropbox.com/s/s7jga3f0dreavlb/video-of-a-man-laughing-and-happy-1608393-360p.mp4?dl=1" \
216+
--background \
217+
"https://www.dropbox.com/s/b22ss59j6pp83zy/brown-landscape-under-grey-sky-3244513.jpg?dl=1" \
218+
--show-output \
219+
--threshold=0.75 \
220+
--mask-blur=5
221+
```
222+
223+
Video Source: [Video Of A Man Laughing And Happy](https://www.pexels.com/video/video-of-a-man-laughing-and-happy-1608393/)
224+
225+
Background: [Brown Landscape Under Grey Sky](https://www.pexels.com/photo/brown-landscape-under-grey-sky-3244513/)
226+
227+
#### Capture Webcam and adding mask overlay
144228

145229
```bash
146230
python -m tf_bodypix \
@@ -187,11 +271,14 @@ python -m tf_bodypix \
187271
python -m tf_bodypix \
188272
replace-background \
189273
--source webcam:0 \
190-
--background /path/to/background-image.jpg \
191-
--output /dev/videoN \
192-
--threshold=0.75
274+
--background \
275+
"https://www.dropbox.com/s/b22ss59j6pp83zy/brown-landscape-under-grey-sky-3244513.jpg?dl=1" \
276+
--threshold=0.75 \
277+
--output /dev/videoN
193278
```
194279

280+
Background: [Brown Landscape Under Grey Sky](https://www.pexels.com/photo/brown-landscape-under-grey-sky-3244513/)
281+
195282
## TensorFlow Lite support (experimental)
196283

197284
The model path may also point to a TensorFlow Lite model (`.tflite` extension). Whether that actually improves performance may depend on the platform and available hardware.
@@ -236,6 +323,30 @@ docker run --rm \
236323
--threshold=0.75
237324
```
238325

326+
## Example Media
327+
328+
Here are a few example media files you could try.
329+
330+
Images:
331+
332+
* [Serious black businesswoman sitting at desk in office](https://www.dropbox.com/s/7tsaqgdp149d8aj/serious-black-businesswoman-sitting-at-desk-in-office-5669603.jpg?dl=1) ([Source](https://www.pexels.com/photo/serious-black-businesswoman-sitting-at-desk-in-office-5669603/))
333+
* [Woman Wearing Gray Notch Lapel Suit Jacket](https://www.dropbox.com/s/ygfudebvbm1pksk/woman-wearing-gray-notch-lapel-suit-jacket-2381069-small.jpg?dl=1) ([Source](https://www.pexels.com/photo/woman-wearing-gray-notch-lapel-suit-jacket-2381069/))
334+
* [Smiling Woman Standing In Front Of A Colorful Flag](https://www.dropbox.com/s/ddyj89vkz7cmzmg/smiling-woman-standing-in-front-of-a-colorful-flag-5255422-small.jpg?dl=1) ([Source](https://www.pexels.com/photo/smiling-woman-standing-in-front-of-a-colorful-flag-5255422/))
335+
* [Man and Woman Smiling Inside Building](https://www.dropbox.com/s/5z7v5wtwx3dmrdu/man-and-woman-smiling-inside-building-1367269-small.jpg?dl=1) ([Source](https://www.pexels.com/photo/man-and-woman-smiling-inside-building-1367269/))
336+
* [Two Woman in Black Sits on Chair Near Table](https://www.dropbox.com/s/dq9e2dv86qd9ror/two-woman-in-black-sits-on-chair-near-table-1181605-small.jpg?dl=1) ([Source](https://www.pexels.com/photo/two-woman-in-black-sits-on-chair-near-table-1181605/))
337+
* [Female barista in beanie and apron resting chin on had](https://www.dropbox.com/s/88qb3yldsb4l2id/female-barista-in-beanie-and-apron-resting-chin-on-had-4350057-small.jpg?dl=1) ([Source](https://www.pexels.com/photo/female-barista-in-beanie-and-apron-resting-chin-on-had-4350057/))
338+
* [Smiling Woman Holding White Android Smartphone While Sitting Front of Table](https://www.dropbox.com/s/43awel6e1mxja5v/smiling-woman-holding-white-android-smartphone-while-sitting-front-of-table-1462631-small.jpg?dl=1) ([Source](https://www.pexels.com/photo/smiling-woman-holding-white-android-smartphone-while-sitting-front-of-table-1462631/))
339+
* [Woman Having Coffee and Rice Bowl](https://www.dropbox.com/s/zndltp65n93poy2/woman-having-coffee-and-rice-bowl-4058316-small.jpg?dl=1) ([Source](https://www.pexels.com/photo/woman-having-coffee-and-rice-bowl-4058316/))
340+
* [Woman Smiling While Holding a Coffee Cup](https://www.dropbox.com/s/0txws4j79o9hewr/woman-smiling-while-holding-a-coffee-cup-6787913-small.jpg?dl=1) ([Source](https://www.pexels.com/photo/woman-smiling-while-holding-a-coffee-cup-6787913/))
341+
342+
Videos:
343+
344+
* [Video Of A Man Laughing And Happy](https://www.dropbox.com/s/s7jga3f0dreavlb/video-of-a-man-laughing-and-happy-1608393-360p.mp4?dl=1) ([Source](https://www.pexels.com/video/video-of-a-man-laughing-and-happy-1608393/))
345+
346+
Background:
347+
348+
* [Brown Landscape Under Grey Sky](https://www.dropbox.com/s/b22ss59j6pp83zy/brown-landscape-under-grey-sky-3244513.jpg?dl=1) ([Source](https://www.pexels.com/photo/brown-landscape-under-grey-sky-3244513/))
349+
239350
## Experimental Downstream Projects
240351

241352
* [Layered Vision](https://github.com/de-code/layered-vision) is an experimental project using the `tf-bodypix` Python API.

‎tf_bodypix/cli.py‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -583,12 +583,16 @@ def get_app(self, args: argparse.Namespace) -> AbstractWebcamFilterApp:
583583

584584

585585
def parse_args(argv: List[str] = None) -> argparse.Namespace:
586-
parser = argparse.ArgumentParser()
586+
parser = argparse.ArgumentParser(
587+
'TensorFlow BodyPix (TF BodyPix)',
588+
formatter_class=argparse.ArgumentDefaultsHelpFormatter
589+
)
587590
subparsers = parser.add_subparsers(dest="command")
588591
subparsers.required = True
589592
for sub_command in SUB_COMMANDS:
590593
sub_parser = subparsers.add_parser(
591-
sub_command.name, help=sub_command.description
594+
sub_command.name, help=sub_command.description,
595+
formatter_class=argparse.ArgumentDefaultsHelpFormatter
592596
)
593597
sub_command.add_arguments(sub_parser)
594598

0 commit comments

Comments
 (0)