Metadata-Version: 2.1
Name: tgs
Version: 0.5.0
Summary: A framework to work with lottie / tgs files
Home-page: https://gitlab.com/mattia.basaglia/tgs/
Author: Mattia Basaglia
Author-email: mattia.basaglia@gmail.com
License: GNU Affero General Public License v3 or later (AGPLv3+)
Project-URL: Code, https://gitlab.com/mattia.basaglia/tgs/
Project-URL: Documentation, http://mattia.basaglia.gitlab.io/tgs/index.html
Project-URL: Chat, https://t.me/tgs_stuff
Project-URL: Coverage, http://mattia.basaglia.gitlab.io/tgs/coverage/
Project-URL: Downloads, http://mattia.basaglia.gitlab.io/tgs/downloads.html
Description: Telegram Animated Stickers Tools
        ================================
        
        A Python framework to work with Telegram animated stickers.
        
        
        Scripts
        -------
        
        * `bin/tgsconvert.py`
        
          Script that can convert between several formats, including lottie / TGS
        
        * `bin/tgscat.py`
        
          Prints the given tgs / lottie file into a human-readable format
        
        * `bin/tgsdiff.py`
        
          Shows a side-by-side diff of the human-readable rendition of two tgs / lottie files
        
        * `bin/tgs2svg.py`
        
          Extracts a frame as SVG from a lottie/tgs file, has a couple more options than `bin/tgsconvert.py`
        
        * `bin/raster2tgs.py`
        
          Converts a sequence of raster images into a lottie/tgs file, has a couple more options than `bin/tgsconvert.py`
        
        * `bin/raster_palette.py`
        
          Shows the palette of a raster image, to use with `bin/raster2tgs.py`
        
        * `bin/tgscolor.py`
        
          Converts a CSS color into a normalized array, as used in lottie
        
        * `bin/jsoncat.py`
        
          Pretty prints a JSON file (useful to debug / diff lottie files)
        
        * `bin/jsondiff.py`
        
          Pretty prints two JSON files side by side, highlighting differences (useful to debug / diff lottie files)
        
        * `bin/tgscat.py`
        
          Pretty prints a tgs / lottie file with more readable annotations (useful to debug / diff lottie files)
        
        * `bin/tgsdiff.py`
        
          Pretty prints two tgs / lottie files side by side, highlighting differences (useful to debug / diff lottie files)
        
        * `bin/tgscheck.py`
        
          Checks a lottie or tgs file to see if it's compatible with telegram stickers
        
        
        Installation
        ------------
        
        
        ### Synfig
        
        There's a Synfig studio plugin to export telegram stickers.
        To install, just copy (or symlink) ./addons/synfig/tgs-exporter
        into the synfig plugin directory.
        You might have to copy ./lib/tgs in there as well.
        
        You can download a zipfile from http://mattia.basaglia.gitlab.io/tgs/downloads.html
        
        
        ### Inkscape
        
        There are some import/export extensions for inkscape.
        
        Just copy (or symlink) the files under ./addons/inkscape to the inkscape extension
        directory.
        On my system that's ~/.config/inkscape/extensions/ but you can double check from
        Inkscape: Edit > Preferences... > System > User extensions
        
        Note that the extensions require Python 3.
        If they are run with a python 2 interpreter, they will try to run themselves using `python3`.
        
        They also need the tgs framework to be in the python path, otherwise you can manually
        set the path on the import/export dialogues.
        
        See also https://inkscape.org/~mattia.basaglia/%E2%98%85tgslottie-importexport
        
        You can download a zipfile from http://mattia.basaglia.gitlab.io/tgs/downloads.html
        
        
        ### Blender
        
        There are some export addons for blender.
        
        Copy (or symlink) the files under ./addons/blender to the Blender extension
        directory.
        
        On my system that's ~/.config/blender/2.80/scripts/addons/ you can check available
        paths through the Blender Python console:
        
            import addon_utils; print(addon_utils.paths())
        
        You can also install the addon from Blender using the zipfile created by `make`.
        
        You can download a zipfile from http://mattia.basaglia.gitlab.io/tgs/downloads.html
        
        
        ### Pip
        
        You can install from pypi:
        
            pip install tgs
        
        from git:
        
            pip install git+https://gitlab.com/mattia.basaglia/tgs.git@master
        
        for the source directory:
        
            pip install /path/to/the/sources # this is the path where setup.py is located
        
        
        Requirements
        ------------
        
        Python 3.
        
        
        ### Optional Requirements
        
        * `coverage`                            To show unit test coverage, used optionally by `test.sh`
        * `pillow`, `pypotrace>=0.2`, `numpy`, `scipy` To convert raster images into vectors
        * `pillow`                              To load image assets
        * `cairosvg`                            To export PNG / PDF / PS
        * `cairosvg`, `pillow`                  To export GIF
        * `cairosvg`, `numpy`, Python OpenCV 2  To export video
        * `fonttools`                           To render text as shapes
        
        
        Features
        --------
        
        Here is a list of features of the tgs python framework:
        
        * Loading compressed TGS and uncompressed lottie JSON
        * Importing SVG images
        * Importing raster images and convert them into vectors
        * Export lottie JSON or TGS
        * Export (non-animated) SVG
        * Importt/Export Synfig files
        * Export PNG/PDF/PostScript
        * Export GIF
        * Export Animated WebP
        * Export Video (MP4, AVI, WebM)
        * Manipulation of lottie objects
        * Simple animation presets (eg: shake, linear bounce)
        * Bezier path animations (eg: follow path, making paths appear and disappear)
        * Wave distortion animation (eg: for flags)
        * Pseudo-3D rotations
        * Animation easing functions
        * Inverse Kinematic solver
        * Pretty printing and comparison of lottie files
        * Rendering text as shapes
        
        
        Reverse Engineering
        -------------------
        
        I had to reverse engineer the format because Telegram couldn't be bothered
        providing the specs.
        
        A TGS file is a gzip compressed JSON, the JSON data is described here:
        https://mattia.basaglia.gitlab.io/tgs/group__Lottie.html#lottie_json
        
        ### Making your own exporters converters
        
        #### Lottie format
        
        If you can get the source image into lottie format, that's 90% of the work done.
        
        I've created Python classes based the format schema and after effects documentation, which
        output the correct json. Eg:
        
            foo = tgs.Animation()
            # ...
            json.dump(foo.to_dict(), output_file)
        
        I'm also creating a proper documentation for the format, see:
        https://mattia.basaglia.gitlab.io/tgs/group__Lottie.html#details
        
        #### TGS changes
        
        Nothing major, just ensure the root JSON object has `tgs: 1`
        
        #### Gzipping
        
        The tgs file is the JSON described above compressed into a gzip,
        and renamed to .tgs
        
        
        #### Unsupported features
        
        Telegram doesn't support everything in the Lottie format.
        https://core.telegram.org/animated_stickers lists some things that are unsupported
        but what is listed there isn't correct.
        
        There are several things marked as unsupported in telegram animated stickers that are actually supported:
        
        * Masks
        * Mattes (Works on desktop but not on Android)
        * Star Shapes
        * Gradient Strokes
        * Repeaters
        * Solids
        * Time Remapping (Works on desktop but not on Android)
        
        
        The following things are actually unsupported:
        
        * Layer Effects
        * Images
        * Skew transforms (this isn't listed in the unsupported features)
        * Texts
        * Animated layer transforms (not listed as unsupported)
        
        
        Things marked as unsupported that I haven't tested:
        
        * Expressions
        * 3D Layers
        * Merge Paths
        * Time Stretching
        * Auto-Oriented Layers
        
        
        License
        -------
        
        AGPLv3+ https://www.gnu.org/licenses/agpl-3.0.en.html
        
        
        Credits
        -------
        
        Copyright 2019 (C) Mattia Basaglia
        
        
        Links
        -----
        
        ### Documentation
        
        http://mattia.basaglia.gitlab.io/tgs/index.html
        
        ### Code
        
        https://gitlab.com/mattia.basaglia/tgs/
        
        ### Chat
        
        https://t.me/tgs_stuff
        
        ### Download
        
        https://gitlab.com/mattia.basaglia/tgs/-/jobs/artifacts/master/download?job=build
        
        Here you can download packages for pip, blender, and inkscape before they are released.
        These packages always have the latest features but they might be unstable.
        
Keywords: telegram stickers tgs lottie svg animation
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3
Description-Content-Type: text/markdown
Provides-Extra: Vectorization
Provides-Extra: Load image
Provides-Extra: PNG
Provides-Extra: Text
Provides-Extra: Video output
Provides-Extra: Advanced Emoji Replacement
