Warning, /graphics/glaxnimate/data/lib/python-lottie/README.md is written in an unsupported language. File is not indexed.
0001 Python Lottie 0002 ============= 0003 0004 A Python framework to work with Lottie files and Telegram animated stickers. 0005 0006 0007 Quick start 0008 ----------- 0009 0010 This section describes some common things you might want to do without having 0011 to read the whole README 0012 0013 ### Installation 0014 0015 pip install lottie 0016 0017 ### Converting into images 0018 0019 This package provide the script `lottie_convert.py`, it's precise location 0020 depends on how you installed python-lottie. 0021 0022 For PNG, GIF, and Webp you have to install `cairosvg` and `pillow`. 0023 0024 To render a still image: 0025 0026 lottie_convert.py input_file.json output_file.png --frame 30 0027 0028 0029 To render an animated image (GIF or WebP): 0030 0031 lottie_convert.py input_file.json output_file.webp 0032 0033 0034 A list of supported formats is described in the section "Supported Formats" below. 0035 0036 0037 ### Turning GIF and such into animations 0038 0039 The lottie format is for vector graphics, this means converting raster images 0040 usually doesn't work too well. 0041 0042 That said, python-lottie does support a few different algorithms to import 0043 raster images, the process is a bit slow for larger images but use it with caution. 0044 0045 To use the potrace vectorization library, install the extras tagged as "trace". 0046 0047 Once set up, just invoke `lottie_convert.py` using the vectorization algorithm 0048 0049 lottie_convert.py input_file.gif output_file.json --bmp-mode trace 0050 0051 For pixel art, you can use the `pizel` algorithm, which doesn't require potrace 0052 0053 lottie_convert.py input_file.gif output_file.json --bmp-mode pixel 0054 0055 If you are ok with keeping raster images as such, you can use the default mode 0056 0057 lottie_convert.py input_file.gif output_file.json 0058 0059 ### Converting Telegram animated stickers (tgs) 0060 0061 This format is natively supported by python lottie, but telegram doesn't 0062 support all of the features supported by lottie 0063 (see the section labeled "Supported After Effects Features" for details). 0064 0065 When converting from tgs, nothing special is needed as it's handled as a lottie animation. 0066 0067 lottie_convert.py AnimatedSticker.tgs output_file.webp 0068 0069 But when converting into animated stickers, you might end up with a file that 0070 Telegram doesn't recognize. To help with this, by default `lottie_convert.py` 0071 will scale the animation to be the right size and framerate. 0072 It will also print out any warnings related to unsupported features. 0073 Everything else works like any other conversion: 0074 0075 lottie_convert.py input_file.json output_file.tgs 0076 0077 If you want to see the same warnings for an existing tgs file use `tgs_check.py` 0078 0079 tgs_check.py AnimatedSticker.tgs 0080 0081 0082 ### Creating animations from scratch 0083 0084 See the examples at https://mattbas.gitlab.io/python-lottie/examples.html 0085 and read the available lottie objects at https://mattbas.gitlab.io/python-lottie/group__Lottie.html#details 0086 0087 0088 Features 0089 -------- 0090 0091 Here is a list of features of the lottie python framework: 0092 0093 * Loading compressed TGS and uncompressed lottie JSON 0094 * Manipulation of lottie objects 0095 * Simple animation presets (eg: shake, linear bounce) 0096 * Bezier path animations (eg: follow path, making paths appear and disappear) 0097 * Wave distortion animation (eg: for flags) 0098 * Pseudo-3D rotations 0099 * Animation easing functions 0100 * Inverse Kinematic solver 0101 * Pretty printing and comparison of lottie files 0102 * Rendering text as shapes 0103 0104 0105 ## Supported Formats 0106 0107 | Format | Import | Import Animated | Export | Export Animated | 0108 |-----------|-----------|-------------------|-----------|-------------------| 0109 | lottie | 👍 | 👍 | 👍 | 👍 | 0110 | tgs | 👍 | 👍 | 👍 | 👍 | 0111 | SVG | 👍 | 👍 | 👍 | ⛔️ | 0112 | SVGz | 👍 | 👍 | 👍 | ⛔️ | 0113 | PNG | 👍 | 👍[^frames] | 👍 | ⛔️ | 0114 | Synfig | 👍 | 👍 | 👍 | 👍 | 0115 | WebP | 👍 | 👍 | 👍 | 👍 | 0116 | dotLottie | 👍 | 👍 | 👍 | 👍 | 0117 | PostScript| ⛔️ | ⛔️ | 👍 | ⛔️ | 0118 | PDF | ⛔️ | ⛔️ | 👍 | ⛔️ | 0119 | BMP | 👍 | 👍[^frames] | ⛔️ | ⛔️ | 0120 | GIF | 👍 | 👍 | 👍 | 👍 | 0121 | TIFF | 👍 | 👍 | 👍 | 👍 | 0122 | MP4 | ⛔️ | ⛔️ | 👍 | 👍 | 0123 | AVI | ⛔️ | ⛔️ | 👍 | 👍 | 0124 | WebM | ⛔️ | ⛔️ | 👍 | 👍 | 0125 | HTML | ⛔️ | ⛔️ | 👍 | 👍 | 0126 | Blender | 👍[^blend]| 👍[^blend] | ⛔️ | ⛔️ | 0127 | Krita | 👍 | ⛔️ | ⛔️ | ⛔️ | 0128 0129 [^frames]: Importing multiple images as frames 0130 0131 [^blend]: Conversion available as a Blender addon 0132 0133 0134 0135 Scripts 0136 ------- 0137 0138 python-lottie provides several scripts to convert or manage lottie animations. 0139 For full documentation see https://mattbas.gitlab.io/python-lottie/scripts.html 0140 0141 The main one is `lottie_convert.py`, which can be used to convert between the supported formats. 0142 0143 There is also the script `lottie_gui.py` which provides a graphical interface for lottie playback. 0144 0145 0146 0147 Installation 0148 ------------ 0149 0150 ### Downloads 0151 0152 The packages for the various applications listed below can be downloaded from here: 0153 0154 * [Releases](https://gitlab.com/mattbas/python-lottie/-/releases) 0155 * [Development Snapshot](https://mattbas.gitlab.io/python-lottie/downloads.html) 0156 0157 0158 ### Synfig 0159 0160 There's a Synfig studio plugin to export telegram stickers. 0161 To install, just copy (or symlink) ./addons/synfig/pylot-exporter 0162 into the synfig plugin directory. 0163 You might have to copy ./lib/lottie in there as well. 0164 0165 0166 ### Inkscape 0167 0168 There are some import/export extensions for inkscape. 0169 0170 Just copy (or symlink) the files under ./addons/inkscape to the inkscape extension 0171 directory. 0172 On my system that's ~/.config/inkscape/extensions/ but you can double check from 0173 Inkscape: Edit > Preferences... > System > User extensions 0174 0175 Note that the extensions require Python 3. 0176 If they are run with a python 2 interpreter, they will try to run themselves using `python3`. 0177 0178 They also need the lottie framework to be in the python path, otherwise you can manually 0179 set the path on the import/export dialogues. 0180 0181 See also https://inkscape.org/~mattia.basaglia/%E2%98%85tgslottie-importexport 0182 0183 0184 ### Blender 0185 0186 There are some export addons for blender. 0187 0188 Copy (or symlink) the files under ./addons/blender to the Blender extension 0189 directory. 0190 0191 On my system that's ~/.config/blender/2.80/scripts/addons/ you can check available 0192 paths through the Blender Python console: 0193 0194 import addon_utils; print(addon_utils.paths()) 0195 0196 You can also install the addon from Blender using the zipfile created by `make`. 0197 0198 0199 ### Pip 0200 0201 You can install from pypi: 0202 0203 pip install lottie 0204 0205 from git: 0206 0207 pip install git+https://gitlab.com/mattbas/python-lottie.git@master 0208 0209 for the source directory: 0210 0211 pip install /path/to/the/sources # this is the path where setup.py is located 0212 0213 0214 Requirements 0215 ------------ 0216 0217 Python 3. 0218 0219 0220 ### Optional Requirements 0221 0222 In order to provide lean installations, this framework doesn't have dependencies 0223 for its core functionality. 0224 0225 To add support for extra formats or advanced functionality, you can install 0226 additional packages. 0227 0228 These requirements are declared as extra in the Pypi package, 0229 follows a table listing dependencies and features 0230 0231 0232 | Packages | Extra | Feature | 0233 |-----------------------------------------------|-------|-----------------------------------------------------------| 0234 | `pillow` | images| To load image assets | 0235 | `cairosvg` | PNG | To export PNG / PDF / PS | 0236 | `cairosvg`, `pillow` | GIF | To export GIF and animated WebP | 0237 | `fonttools` | text | To render text as shapes | 0238 | `grapheme` | emoji | Adding emoji support to text rendering | 0239 | `cairosvg`, `numpy`, Python OpenCV 2 | video | To export video | 0240 | `pillow`, `pypotrace>=0.2`, `numpy`, `scipy` | trace | To convert raster images into vectors | 0241 | `QScintilla` | GUI | Grafical user interface utilities | 0242 | `coverage` | | To show unit test coverage, used optionally by `test.sh` | 0243 0244 0245 If intalling from pip, you can install optional requirements like so: 0246 0247 pip install lottie[GIF] 0248 0249 The above example will ensure `cairosvg` and `pillow` are installed. 0250 For more details see https://pip.pypa.io/en/latest/reference/pip_install/#examples. 0251 0252 For convenience, an additional extra requirements is defined, 0253 so you can install all dependencies at once: 0254 0255 pip install lottie[all] 0256 0257 If you are using python-lottie from source you can run 0258 0259 pip install -r requirements.txt 0260 0261 Which will install all the requirements (except for pypotrace, as that package has some issues) 0262 0263 0264 Telegram Animated Stickers 0265 -------------------------- 0266 0267 I had to reverse engineer the format because Telegram couldn't be bothered 0268 providing the specs. 0269 0270 A TGS file is a gzip compressed JSON, the JSON data is described here: 0271 https://mattbas.gitlab.io/python-lottie/group__Lottie.html#lottie_json 0272 0273 ### Making your own exporters converters 0274 0275 #### Lottie format 0276 0277 If you can get the source image into lottie format, that's 90% of the work done. 0278 0279 I've created Python classes based the format schema and after effects documentation, which 0280 output the correct json. Eg: 0281 0282 foo = lottie.Animation() 0283 # ... 0284 json.dump(foo.to_dict(), output_file) 0285 0286 I'm also creating a proper documentation for the format, see: 0287 https://mattbas.gitlab.io/tgs/group__Lottie.html#details 0288 0289 #### TGS changes 0290 0291 Nothing major, just ensure the root JSON object has `tgs: 1` 0292 0293 #### Gzipping 0294 0295 The tgs file is the JSON described above compressed into a gzip, 0296 and renamed to .tgs 0297 0298 0299 License 0300 ------- 0301 0302 AGPLv3+ https://www.gnu.org/licenses/agpl-3.0.en.html 0303 0304 0305 Credits 0306 ------- 0307 0308 Copyright 2019 (C) Mattia Basaglia 0309 0310 0311 Links 0312 ----- 0313 0314 ### Documentation 0315 0316 https://mattbas.gitlab.io/python-lottie/index.html 0317 0318 ### Code 0319 0320 https://gitlab.com/mattbas/python-lottie/ 0321 0322 ### Chat 0323 0324 https://t.me/tgs_stuff 0325 0326 ### Download 0327 0328 https://mattbas.gitlab.io/python-lottie/downloads.html 0329 0330 Here you can download packages for pip, blender, and inkscape before they are released. 0331 These packages always have the latest features but they might be unstable. 0332 0333 ### Issues 0334 0335 You can report any issue in the tracker on gitlab: 0336 0337 https://gitlab.com/mattbas/python-lottie/-/issues 0338 0339 0340 Supported After Effects Features 0341 -------------------------------- 0342 0343 Compare with http://airbnb.io/lottie/#/supported-features 0344 0345 ### Legend 0346 0347 * 👍 Supported 0348 * ❔ Unknown / untested 0349 * ⛔️ Not supported 0350 * **python-lottie** refers to this framework in general 0351 * **Telegram** refers to features supported by telegram animated stickers 0352 * **SVG** refers to the exported SVG images from this framework, 0353 features supported here will also reflect on other formats (such as video, png, and similar) 0354 0355 0356 Telegram doesn't support everything in the Lottie format. 0357 https://core.telegram.org/animated_stickers lists some things that are unsupported 0358 but what is listed there isn't correct. 0359 0360 There are several things marked as unsupported in telegram animated stickers that are actually supported. 0361 0362 0363 0364 | **Shapes** | **python-lottie** | **Telegram** | **SVG** | 0365 |----------------------------------|-------------------|------------------|---------| 0366 | Shape | 👍 | 👍 | 👍 | 0367 | Ellipse | 👍 | 👍 | 👍 | 0368 | Rectangle | 👍 | 👍 | 👍 | 0369 | Rounded Rectangle | 👍 | 👍 | 👍 | 0370 | Polystar | 👍 | 👍[^unsuported] | 👍 | 0371 | Group | 👍 | 👍 | 👍 | 0372 | Trim Path (individually) | 👍 | 👍 | 👍 | 0373 | Trim Path (simultaneously) | 👍 | 👍 | 👍 | 0374 | **Fills** | **python-lottie** | **Telegram** | **SVG** | 0375 | Color | 👍 | 👍 | 👍 | 0376 | Opacity | 👍 | 👍 | 👍 | 0377 | Radial Gradient | 👍 | 👍 | 👍 | 0378 | Linear Gradient | 👍 | 👍 | 👍 | 0379 | Fill Rule | 👍 | 👍 | 👍 | 0380 | **Strokes** | **python-lottie** | **Telegram** | **SVG** | 0381 | Color | 👍 | 👍 | 👍 | 0382 | Opacity | 👍 | 👍 | 👍 | 0383 | Width | 👍 | 👍 | 👍 | 0384 | Line Cap | 👍 | 👍 | 👍 | 0385 | Line Join | 👍 | 👍 | 👍 | 0386 | Miter Limit | 👍 | 👍 | 👍 | 0387 | Dashes | 👍 | 👍 | 👍 | 0388 | Gradient | 👍 | 👍[^unsuported] | 👍 | 0389 | **Transforms** | **python-lottie** | **Telegram** | **SVG** | 0390 | Position | 👍 | 👍 | 👍 | 0391 | Position (separated X/Y) | 👍 | 👍 | 👍 | 0392 | Scale | 👍 | 👍 | 👍 | 0393 | Rotation | 👍 | 👍 | 👍 | 0394 | Anchor Point | 👍 | 👍 | 👍 | 0395 | Opacity | 👍 | 👍 | 👍 | 0396 | Parenting | 👍 | 👍 | 👍 | 0397 | Skew | 👍 | ⛔️[^bug] | 👍 | 0398 | Auto Orient | 👍 | 👍[^unsuported] | 👍 | 0399 | **Interpolation** | **python-lottie** | **Telegram** | **SVG** | 0400 | Linear Interpolation | 👍 | 👍 | 👍 | 0401 | Bezier Interpolation | 👍 | 👍 | 👍 | 0402 | Hold Interpolation | 👍 | 👍 | 👍 | 0403 | Spatial Bezier Interpolation | 👍 | 👍 | 👍 | 0404 | Rove Across Time | ⛔️ | ⛔️[^untested] | ⛔️ | 0405 | **Masks** | **python-lottie** | **Telegram** | **SVG** | 0406 | Mask Path | 👍 | 👍[^unsuported] | 👍 | 0407 | Mask Opacity | 👍 | 👍[^unsuported] | 👍 | 0408 | Add | 👍 | 👍[^unsuported] | ⛔️ | 0409 | Subtract | 👍 | 👍[^unsuported] | ⛔️ | 0410 | Intersect | 👍 | 👍[^unsuported] | 👍 | 0411 | Lighten | 👍 | 👍[^unsuported] | ⛔️ | 0412 | Darken | 👍 | 👍[^unsuported] | ⛔️ | 0413 | Difference | 👍 | 👍[^unsuported] | ⛔️ | 0414 | Expansion | 👍 | 👍[^unsuported] | ⛔️ | 0415 | Feather | 👍 | 👍[^unsuported] | ⛔️ | 0416 | **Mattes** | **python-lottie** | **Telegram** | **SVG** | 0417 | Alpha Matte | 👍 | ⛔️[^dok] | 👍 | 0418 | Alpha Inverted Matte | 👍 | ⛔️[^dok] | ⛔️ | 0419 | Luma Matte | 👍 | ⛔️[^dok] | 👍 | 0420 | Luma Inverted Matte | 👍 | ⛔️[^dok] | ⛔️ | 0421 | **Merge Paths** | **python-lottie** | **Telegram** | **SVG** | 0422 | Merge | ⛔️ | ⛔️[^untested] | ⛔️ | 0423 | Add | ⛔️ | ⛔️[^untested] | ⛔️ | 0424 | Subtract | ⛔️ | ⛔️[^untested] | ⛔️ | 0425 | Intersect | ⛔️ | ⛔️[^untested] | ⛔️ | 0426 | Exclude Intersection | ⛔️ | ⛔️[^untested] | ⛔️ | 0427 | **Layer Effects** | **python-lottie** | **Telegram** | **SVG** | 0428 | Fill | 👍 | ⛔️ | ⛔️ | 0429 | Stroke | 👍 | ⛔️ | ⛔️ | 0430 | Tint | 👍 | ⛔️ | ⛔️ | 0431 | Tritone | 👍 | ⛔️ | ⛔️ | 0432 | Levels Individual Controls | 👍 | ⛔️ | ⛔️ | 0433 | **Text** [^text] | **python-lottie** | **Telegram** | **SVG** | 0434 | Glyphs | 👍 | ⛔️ | ⛔️ | 0435 | Fonts | 👍 | ⛔️ | ⛔️ | 0436 | Transform | 👍 | ⛔️ | ⛔️ | 0437 | Fill | 👍 | ⛔️ | 👍 | 0438 | Stroke | 👍 | ⛔️ | ⛔️ | 0439 | Tracking | ⛔️ | ⛔️ | ⛔️ | 0440 | Anchor point grouping | ⛔️ | ⛔️ | ⛔️ | 0441 | Text Path | ⛔️ | ⛔️ | ⛔️ | 0442 | Per-character 3D | ⛔️ | ⛔️ | ⛔️ | 0443 | Range selector (Units) | ⛔️ | ⛔️ | ⛔️ | 0444 | Range selector (Based on) | ⛔️ | ⛔️ | ⛔️ | 0445 | Range selector (Amount) | ⛔️ | ⛔️ | ⛔️ | 0446 | Range selector (Shape) | ⛔️ | ⛔️ | ⛔️ | 0447 | Range selector (Ease High) | ⛔️ | ⛔️ | ⛔️ | 0448 | Range selector (Ease Low) | ⛔️ | ⛔️ | ⛔️ | 0449 | Range selector (Randomize order) | ⛔️ | ⛔️ | ⛔️ | 0450 | expression selector | ⛔️ | ⛔️ | ⛔️ | 0451 | **Other** | **python-lottie** | **Telegram** | **SVG** | 0452 | Expressions | ⛔️ | ⛔️[^untested] | ⛔️ | 0453 | Images | 👍 | ⛔️ | 👍 | 0454 | Precomps | 👍 | 👍 | 👍 | 0455 | Time Stretch | 👍 | ⛔️ | ⛔️ | 0456 | Time remap | 👍 | ⛔️[^dok] | 👍 | 0457 | Markers | ⛔️ | ⛔️[^untested] | ⛔️ | 0458 | 3D Layers | 👍 | ⛔️[^untested] | ⛔️ | 0459 | Repeaters | 👍 | 👍[^unsuported] | 👍 | 0460 | Solids | 👍 | 👍[^unsuported] | 👍 | 0461 0462 [^text]: Note that **python-lottie** offers an alternative to lottie text layers, and can render 0463 text as shapes, so that is supported everywhere 0464 0465 [^untested]: Marked as unsuported but I haven't tested it 0466 0467 [^bug]: Not listed as unsupported, maybe a bug? 0468 0469 [^dok]: Works on telegram desktop 0470 0471 [^unsuported]: Marked as unsupported