FreeBSD Manual Pages
FLIF(1) User Commands FLIF(1) NAME flif - convert image files from or to FLIF SYNOPSIS flif [OPTION]... [-d] input_file.flif output_file flif [OPTION]... [-e] input_file... output_file.flif flif [OPTION]... [-t] input_file.flif output_file.flif DESCRIPTION This program can encode and decode images in the Free Lossless Image Format (FLIF). Input and output formats can be either PNG, PAM, PNM (PPM, PGM, PBM) or FLIF. Metadata can be extracted or inserted using input/output files with specific extensions: ICC color profiles (with extension .icc), Exif metadata (extension .exif), or XMP metadata (ex- tension .xmp). flif will automatically deduce the action (encode, decode or transcode) from the names and contents of the files. The specifiers -e (encode), -d (decode) and -t (transcode) are optional and can be safely omitted. The extension of the output file (the last argument) determines the im- age format that is used. The special name '-' means standard input or output, depending on the position. In this case, the action has to be specified explicitly, and the only supported image formats are FLIF and PAM/PNM. For example, flif -e - - encodes a PPM file from standard input to a FLIF file writ- ten to standard output; flif -e input.ppm - | flif -d - output.png is a very slow way to convert a PPM file to a PNG file. OPTIONS The general options are: -v, --verbose Increases verbosity. By default, flif is silent (unless there is a problem). Adding one or more -v will produce more output. Verbose output normally goes to standard output; error messages go to standard error. If the output file is '-' (standard out- put), then all messages go to standard error. -h, --help Display help and quit. Use in combination with -v for help on advanced features. -o, --overwrite By default, flif does not overwrite existing files. To force it to overwrite the output file, use this option. -c, --no-crc FLIF files can optionally contain a CRC to verify the integrity of the image data. The default is to check the CRC when decod- ing, and to include a CRC when encoding (unless the image is tiny). This option changes the default behavior as follows: When decoding: don't check the CRC. When encoding: don't in- clude a CRC. -p, --no-color-profile FLIF files can optionally include an ICC color profile. When converting to or from PNG, the color profile will be copied (if there is any). This option forces the encoder/decoder to strip the color profile. -m, --no-metadata FLIF files can optionally include metadata (Exif and/or XMP). This option forces the encoder/decoder to strip metadata. -k, --keep-palette By default, FLIF reads and writes PNG files as RGB(A) images, converting internal palette representations if needed. This op- tion changes the default behavior as follows: When encoding, this option can be used to preserve the palette of a PNG8 image. This can be useful if the existing palette or- der happens to be particularly good. Without this option, the encoder would probably use a palette transformation even without -k, but it would probably have a different order. When decoding to PNG, this option will produce a palette PNG8 image if the input FLIF file uses a palette internally (and if that palette is compatible with the PNG format, i.e. at most 256 colors and either RGB or RGBA but not an RGB palette plus an in- dependent alpha channel). In both cases, this option also has the advantage of avoiding the conversion to or from RGBA, so it might be somewhat faster and it uses significantly less memory. DECODING To decode a FLIF image, the output filename must have one of the fol- lowing extensions: .png Portable Network Graphics (PNG) .pnm Portable anymap (PNM). If the FLIF image has transparency (alpha channel), it will be discarded. If the image is a grayscale im- age, a PGM (P5) will be produced; otherwise a PPM (P6) is pro- duced. .pam Portable arbitrary map (PAM). If the FLIF image has an alpha channel, a PAM (P7) is produced; otherwise a PPM (P6) or PGM (P5) is produced. .rggb This is a non-standard format which is used to represent raw camera image with RGGB data (i.e. raw Bayer CFA sensor data). It is actually a PGM image as produced by dcraw -E -4. .icc Saves just the ICC color profile, if there is any. .exif Saves just the Exif metadata, if there is any. .xmp Saves just the XMP metadata, if there is any. Alternatively, the special output filename null: can be used if the de- coded output does not need to be saved. This might be useful to verify the integrity of a FLIF image, or to benchmark the decode time. The following decode options are available: -q, --quality=PERCENT FLIF is a lossless format, but it allows you to do a 'lossy de- coding' (i.e. progressive loading), where only the beginning of the file is read (i.e. a partially downloaded FLIF image). The default is -q100 (lossless decoding). The percentage corresponds to the minimal proportion of subpixels that has to be decoded. This option is most effective for interlaced FLIF files. How- ever, it can also be used on non-interlaced FLIF files; in that case the percentage corresponds to the proportion of color chan- nels to decode: e.g. on RGB images (with the YCoCg color trans- form enabled, which is the default), -q33 (or lower) produces a more or less grayscale image (only Y); quality values between 34 and 66 produce a color image with only the orange-blue chroma channel decoded (only Y and Co); values above 67 correspond to a lossless decoding, including the green-magenta chroma channel (Y, Co and Cg). -s, --scale=FACTOR For large images, in many use cases it suffices to load only a scaled-down version of the image, e.g. because the resolution of the target canvas is (much) lower than the image resolution. This option can be used to do a 'lossy decode', like -q. It au- tomatically selects a quality percentage suitable for the de- sired scale-down factor. For an input FLIF image of dimensions width x height, the resulting output image will have dimensions width/FACTOR x height/FACTOR. Only powers of two (1,2,4,8,16,32,...) are allowed as scale-down factors. The scaled-down image is lossy in two ways: all subpixels are subsampled, not averaged (which may result in aliasing arti- facts), and only the (alpha and) luma channels are decoded at the full scaled-down resolution; the chroma channels are rela- tively subsampled (which may result in chroma blockiness). This option is only effective for interlaced FLIF files. -r, --resize=WIDTH[xHEIGHT] Automatically pick a scale-down factor such that the decoded downscaled image fits in target rectangle of WIDTH by HEIGHT pixels. Note that the actual decoded output can be significantly smaller than this: the image aspect ratio is respected, and only power-of-two scale-down factors are used. If the aspect ratio of the target rectangle is equal to the image aspect ratio, then the width of the decoded image is between WIDTH/2 and WIDTH, and the height of the decoded image is between HEIGHT/2 and HEIGHT. If HEIGHT is omitted, it is assumed to be equal to WIDTH. In order to obtain a high-quality scaled-down image that fits a given target rectangle exactly, it is recommended to pick a --resize dimension which is at least two times higher than this target, and use a downscaling method of choice to scale down from that. This option is only effective for interlaced FLIF files. -i, --identify Do not fully decode the input FLIF file, just decode its header and output some metadata like dimensions and color depth. You can specify multiple input files when this option is used. ENCODING To encode an image to FLIF, the input file(s) can be in any of the out- put formats supported by the decoder: PNG, PAM, or PNM. Additionally it is possible to transcode from FLIF to FLIF, which might be useful when using non-default encoder settings. If the input file contains Exif/XMP metadata or an ICC color profile, it will also be included in the output FLIF file, unless the option -m (for metadata) and/or -p (for the color profile) is specified. You can also explicitly add metadata by providing (an) input file(s) with the extension .exif .xmp, and/or .icc. All of the encode options are optional; the defaults are supposed to be OK. If progressive decoding is not useful in your particular use case, then -N might be a good idea, but other than that, it is recommended to simply use the default settings, since all of these options can easily lead to worse compression. The following encode options are available: -E, --effort=EFFORT How much effort to spend on compression, as expressed on a scale from 0 (nearly no effort) to 100 (a lot of effort). The default is -E60. At the moment, most of the values of EFFORT result in the same internal configuration; interesting values to try are: -E0, -E5, -E10, -E20, -E30, -E60, -E80, -E100. There is no guarantee that higher values for EFFORT actually result in smaller files: it is very much possible that a file encoded with -E100 is larger than one encoded with -E10. There is a guaran- tee, however, that more time will be spent for higher values of EFFORT. On average, higher values for EFFORT do result in smaller files, though the difference in file size between -E10 and -E100 is typically small, while the difference in encode time is significant. This option is no substitute for brute-force optimization: even at -E100, there is only one encoding performed. External tools that try many encodings can achieve smaller sizes than -E100. This option is mosty useful to reduce the encode time without really harming compression much. -I, --interlace Force the resulting image to be interlaced (also known as 'pro- gressive'). This is the default setting, except for very small images (currently defined as 'less than 10,000 pixels'), where progressive decoding would be of little use. -N, --no-interlace Force the resulting image to be non-interlaced (also known as 'scanlines'). By default, flif will produce interlaced files. Non-interlaced files tend to be (slightly) smaller for most im- age types, but they cannot be decoded progressively. -Q, --lossy=QUALITY FLIF is a lossless format, but if you want to, you can use this option to modify the image before encoding it, in such a way that it compresses better. The parameter QUALITY indicates the desired quality, where 100 is lossless and 0 is very lossy. -U, --adaptive By default, -Q treats every pixel the same (the same amount of loss is allowed). This option can be used for adaptive lossy en- coding. You have to create a saliency map that indicates the re- gions of interest that should be stored with less loss. The saliency map has to be a grayscale image of the same dimensions as the input image: black means lossy (maximum loss depends on -Q), white means lossless, and intermediate values are interme- diate levels of lossiness. To create the saliency map, you can use external tools like SaliencyDetector (https://github.com/technopagan/mss-saliency). In practice, you may want to darken the saliency map to avoid fully lossless storage. Here is an example: flif -Q50 -U input-image.png saliency-map.png output.flif -K, --keep-invisible-rgb By default, pixels that are fully transparent have undefined RGB values in a FLIF image, since those values are irrelevant for nearly all purposes. If you insist on storing the RGB values hidden behind A=0, use this option. In rare cases this can lead to better compression. ADVANCED ENCODE OPTIONS The options below can be used to manually tune some encoder parameters in order to try to get (slightly) better compression. -P, --max-palette-size=NB_COLORS Images which use relatively few different colors, e.g. ex-GIF images, can be compressed better using a palette of colors in- stead of the full RGB(A) color space. By default, flif uses a palette if the image has less than 512 distinct colors. With this option, you can adjust this threshold. In particular, -P0 disables the use of a color palette. There are two kinds of palettes: Palette_Alpha contains RGBA colors, while Palette contains RGB colors. On images with transparency, it can be the case that there are more than NB_COLORS distinct RGBA colors, but less than NB_COLORS distinct RGB colors; in that case the Alpha channel gets encoded sepa- rately and the Palette transform is used. By default, flif orders the palette in lexicographical order on the transformed color values -- typically (Y,Co,Cg) or (Al- pha,Y,Co,Cg). If NB_COLORS is a negative number, then the palette is not ordered and the colors are added in the order in which they appear in the image (in scanline order). In that case, the maximum palette size is the absolute value of NB_COL- ORS. -A, --force-color-buckets For images which use relatively few different colors, but more than what would fit in a color palette, FLIF implements the Color_Buckets transform to improve compression. By default, flif uses a heuristic to decide whether or not to use Color_Buckets. With this option, Color_Buckets is forced on, unless the image is a grayscale image or uses a palette (so to use color buckets instead of a palette, use -AP0. -B, --no-color-buckets Similar to -A, this option overrides the heuristic and forces Color_Buckets to be disabled. -C, --no-channel-compact This option disables the Channel_Compact transform. This trans- formation reduces the domain of each channel to eliminate unused values. While this typically results in better compression, it is by no means necessarily the case. -Y, --no-ycocg This option disables the YCoCg color transform. This color space transform is aimed at decorrelating the RGB channels, and usu- ally leads to better compression. It also helps to improve the quality of progressive decoding, by encoding the most important Y channel earlier than the chroma channels. -W, --no-subtract-green When specifying -Y, the fallback color transformation is RGB to G(R-G)(B-G), i.e. the Green value gets subtracted from the Red and Blue channels. With this option, the green subtraction is not done. -G, --guess=METHOD[METHOD]... Interlaced FLIF can use different pixel prediction (guess) meth- ods. By default, the encoder uses a simple heuristic to automat- ically pick a good method. This option lets you manually over- ride that choice. -G0 uses the average of top and bottom (H) or left and right (V); -G1 uses the median of top+left-topleft, bottom+left-bottomleft (H) or top+right-topright (V), and the -G0 guess; -G2 uses the median of top, left, and bottom (H) or right (V); -G? picks one of the above predictors, depending on some heuris- tic. This is the default setting. -GX uses different predictors (any of the above) for each plane/zoomlevel, depending on some heuristic. This is usually a bad idea. For photographs, -G0 tends to be better, while for line art, -G1 or -G2 are usually best. You can specify the pixel predictor separately for each plane (Y,Co,Cg,A). Unspecified predictors are set to the Y plane predictor. So for example -G0?2 means: use predictor 0 for the Y plane, an automatically chosen predic- tor for the Co plane, predictor 2 for the Cg plane, and if there's an alpha channel, use predictor 0 (the same as for the Y plane). -H, --invisible-guess=METHOD Interlaced FLIF with an alpha channel can use different pixel prediction methods to define the RGB values of invisible (A=0) pixels. This can have a (small) effect on compression. The available methods are -H0, -H1, and -H2, which have the same meaning as in the option -G (see above). The default method is -H2. -J, --chroma-subsample Interlaced FLIF can be truncated. This option truncates the chroma channels in such a way that a chroma subsampling similar to JPEG's 4:2:0 is obtained. Obviously this introduces loss, since 3/4 of the chroma pixels are not encoded. -R, --maniac-repeats=NB_ITERATIONS The first and computationally most demanding step of FLIF encod- ing is performing a number of iterations of dummy-encoding in order to learn image-adapted MANIAC trees. More iterations will result in larger and better MANIAC trees, resulting in better compression. However, since the trees themselves are part of the compressed file, too many iterations will result in worse overall compression. Also, larger MANIAC trees do have a (slight) negative impact on decode speed. The default value -R2 tends to be near the optimum, but usually -R3, -R4 or -R5 pro- duces a slightly smaller compressed file (at the cost of a longer encode time). For fast encoding without MANIAC trees, use -R0. -T, --maniac_threshold=BITS While constructing a MANIAC tree, a leaf node turns into a deci- sion node (i.e. it splits into two new leaf nodes) when a cer- tain threshold is reached. This threshold can be expressed in the hypothetical number of bits that would have been saved so far if the node would have been split from the beginning. The default setting is -T40 (i.e. 5 bytes). Lower values will cause the MANIAC trees to be more eagerly grown, thus the trees get larger and potentially more 'noisy'. Higher values will result in smaller trees, and potentially less adaptation to the image (so worse compression). -D, --maniac-divisor=DIV After constructing a MANIAC trees, a simple post-processing step takes place. Each inner node in the MANIAC tree contains a counter which determines when the node gets split during the ac- tual encoding or decoding. During learning, the nodes are always split 'too late' (that is, after the split threshold has already been reached). Therefore, the counters are divided by some fixed constant, with the goal of make sure that during actual encod- ing, the splitting takes place 'early enough'. However, de- creasing the counters too much (i.e. a value of DIV that is too high) means that the AC contexts in the inner nodes have no time to adjust, leading to worse compression. The default setting is -D30. -M, --maniac-min-size=SIZE Also as part of the post-processing step after constructing the MANIAC trees, some pruning takes place in order to reduce the size of the trees (which is important since they are part of the compressed file). The pruning will remove leaf nodes and sub- trees that are not frequently visited, i.e. the sum of the coun- ters in the subtree is small. As a result these contexts will be merged with the one of the parent node. This option controls the threshold at which such pruning is done. The default set- ting is -M50, which roughly means that subtrees are pruned if they are used for less than 50/NB_ITERATIONS subpixels. -X, --chance-cutoff=CUTOFF The entropy coding ultimately outputs bits according to some adaptive chance. Chances are represented as 12-bit numbers which represent a rational number of the form x/4096. The lowest pos- sible chance is set at CUTOFF/4096, the highest possible chance is (4096-CUTOFF)/4096. The default value is -X2. If you have an input image that is extremely predictable, you may want to try -X1, which allows chances to converge to more extreme values, resulting in even better compression. If however the input is rather noisy, you could use a higher value like -X20 to limit the cost of bad prediction. (If the input is very noisy, it may be better to not try to compress it in the first place.) -Z, --chance-alpha=ALPHA The chance adaptation in the entropy coding uses this parameter to control how rapidly the chance is allowed to change. If it changes too rapidly, it will fluctuate wildly around the optimal chance instead of converging to it. If it changes too slowly, it will not compress well because it takes too long to adapt. The default value is -Z19 ANIMATION FLIF supports animation, so if multiple input files are given, an ani- mated FLIF file will be produced where each input image corresponds to one frame of the animation. All input images need to have the exact same dimensions (width, height, number of color channels and color depth). All input frames are interpreted as complete frames ('replace mode'); there is no notion of 'combine mode' frames. In other words, transparent pixels are always transparent, they do not combine with the pixels from the previous frame. When decoding an animated FLIF file, multiple output images will be produced. The filenames of the decoded output images are constructed as follows: if the output filename is filename.ext, then the actual output files are filename-000.ext, filename-001.ext, filename-002.ext, ..., filename-<nb_frames - 1>.ext. Custom output filenames can be specified as in C printf(3), e.g. frame%02X.png will produce output files frame00.png, frame01.png, ..., frame09.png, frame0A.png, frame0B.png, ..., frame0F.png, frame10.png, ... When encoding an animated FLIF file, multiple input files can be speci- fied by simply listing all the files, using shell patterns (e.g. frame*.png), or using printf(3)-style notation, as above. Options specific to encoding (or transcoding) animations are as fol- lows: -F, --frame-delay=DELAY[,DELAY]... The time between two consecutive frames of the animation, in milliseconds. The default setting is -f100 (100ms for all frames), which corresponds to 10 frames per second. If multiple delays are given, each number corresponds to the duration of one frame. In case the number of delays is smaller than the number of frames, the last number is repeated implicitly. -L, --max-frame-lookback=NB_FRAMES In animations, typically the frames are somewhat similar. To im- prove compression, FLIF does a generalization of 'combine mode': it will look back at most NB_FRAMES frames to 'reuse' pixels. This transformation is called Frame_Lookback. Using -L0, the method can be disabled. It does not make sense to use a value larger than the number of frames in the animation minus one. The default setting is -L1. Different values can result in bet- ter or worse compression. -S, --no-frame-shape By default, the Frame_Shape transform is enabled. The shape of a frame is described row-by-row, so it is more general than a sim- ple bounding box (e.g. it could also be a sphere or triangle). However, if the shape of the changed pixels is not convex, and if Frame_Lookback is also activated (which is the default set- ting), Frame_Shape does not always produce smaller files. This option can be used to disable the Frame_Shape transform. BUGS Please report all bugs or feature requests to our issue tracker: http://github.com/FLIF-hub/FLIF/issues/ EXAMPLES flif picture.png picture.flif Encode the PNG file picture.png to a FLIF file picture.flif flif picture.ppm profile.icc picture.flif Encode the PPM file picture.ppm and the ICC color profile pro- file.icc to a FLIF file picture.flif flif frame-*.png -F40 -L10 animation.flif Encode a sequence of PNG files (frame-*.png) to an animated FLIF file animation.flif, with a delay of 40ms between each frame (25 frames per second), using a frame lookback of 10 frames. flif -q50 animation.flif decoded_frame.pam Decode the FLIF animation animation.flif at quality 50%, to a series of Portable AnyMap files decoded_frame-000.pam, de- coded_frame-001.pam, decoded_frame-002.pam, ... flif -s2 animation.flif -NAP0 -F50 -L3 -R2 -T38 -D32 -M70 anima- tion_downscaled_and_tweaked.flif Transcode the FLIF animation animation.flif, scaling down by a factor of two, using a non-interlaced encoding, forced color buckets and no palette, a frame delay of 50ms, a lookback of 3 frames, 2 MANIAC learning iterations, a MANIAC split threshold of 38 bits, a node-count divisor of 32, and a post-pruning mini- mal size threshold of 70 subpixels. AUTHORS flif was written by Jon Sneyers and Pieter Wuille, with contributions from many others. The latest source code is available at http://github.com/FLIF-hub/FLIF/ This manual page was written by Jon Sneyers. SEE ALSO viewflif(1), convert(1), png(5), pnm(5), pgm(5), pam(5), dcraw(1) Please refer to http://flif.info/ and http://github.com/FLIF-hub/ for additional information. COPYRIGHT Copyright (C) 2010-2016 Jon Sneyers & Pieter Wuille. LICENSE This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MER- CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. Free Lossless Image Format Jan 4, 2017 FLIF(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | DECODING | ENCODING | ADVANCED ENCODE OPTIONS | ANIMATION | BUGS | EXAMPLES | AUTHORS | SEE ALSO | COPYRIGHT | LICENSE
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=flif&sektion=1&manpath=FreeBSD+Ports+15.0.quarterly>