diff --git a/untranslatable_pages/kra_the_krita_file_format.rst b/untranslatable_pages/kra_the_krita_file_format.rst index 6b7f80d17..5e6098a31 100644 --- a/untranslatable_pages/kra_the_krita_file_format.rst +++ b/untranslatable_pages/kra_the_krita_file_format.rst @@ -1,180 +1,518 @@ .. meta:: :description: Deswcription of the Krita File Format .. metadata-placeholder :authors: - Boudewijn Rempt + - Wolthera van Hövell tot Westerflier :license: GNU free documentation license 1.3 or later. .. _kra_the_krita_file_format.rst: ========================== KRA: The Krita File Format ========================== Krita files have the file name extension .kra. The data is stored within a ZIP file wrapper. Krita can save both as 32 bit as well as 64 bit zip files, depending on the user's settings. Applications reading .kra files should not make any assumptions about compression settings, but only DEFLATED and STORED are used to add files to the store. The format is similar to the OpenRaster and OpenDocument documents. This file format is hereafter referred to as a “kra file” in this specification. It has a number of required and optional standard files and subdirectories within it: :: example.kra [considered as a folder-like object] ├ mimetype ├ documentinfo.xml ├ maindoc.xml ├ example/ │ ├ layers/ │ │ ├ layer │ │ ├ layer1.defaultpixel │ │ ├ layer1.icc │ │ └ layer2.shapelayer/content.svg │ ├ palettes/ │ │ └ palette.kpl │ ├ annotations/ │ │ ├ proofing/icc │ │ └ icc │ └ reference_images/ │ ├ 0.png │ └ 1.png ├ preview.png └ mergedimage.png Required Files -------------- mimetype ~~~~~~~~ The first file in the archive must be called ``"mimetype"``, without a file name extension. It must be STORED without compression. This file must contain the string ``"application/x-krita"``, with no whitespace or trailing newline. documentinfo.xml ~~~~~~~~~~~~~~~~ This is an UTF-8 encoded XML file that contains information about the document. It follows an old-pre OpenDocument specification of which the DTD is no longer available :: example Unknown 1 2020-02-20T15:13:34 2020-02-20T15:13:25 maindoc.xml ~~~~~~~~~~~ This is an UTF-8 encoded XML file that describes the document structure. There is *no* formal definition for ``maindoc.xml`` and the DTD has long since been lost, after it had become unmaintained. In other words, it's defined by example and new versions of Krita will define new sections. Even if the document does not contain an animation, and animation section is present. :: example (image data directory) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This directory has the name of the image. The convention to use the name of the image to form the path to the layer data dates back tot he days when Krita could save more than one image in a kra file. *Note that this is no longer supported.* The image data directory contains three folders: ``layers``, ``palettes`` and ``annotations``. The layers directory contains layer data, the palettes directory palettes (color sets) that are saved with the document and the annotations directory contains in any case the ICC color profile that is used for the image, and can contain other data as well. The layer data consists of three files: ``layer``, ``layer.icc`` and ``layer.defaultpixel``. The layer file contains compressed pixel data. The format of the pixel data is internal to Krita and dependent on the version of Krita and can change without warning. There are currently two compressors: https://invent.kde.org/kde/krita/-/blob/master/libs/image/tiles3/swap/kis_tile_compressor_2.cpp and the legacy compressor for reading older .kra files: https://invent.kde.org/kde/krita/-/blob/master/libs/image/tiles3/swap/kis_legacy_tile_compressor.cpp The ``layer.icc`` file contains the icc profile for the layer, even if it's the same profile as used for the image. Krita .kra files can contain a heterogenous layer stack, that is layers of different colorspaces can occur in the stack. The ``layer.defaultpixel`` file contains a binary representation of a color conforming to the layer's colorspace and defines the default color for pixels that are not defined. + + Vector layers are saved as SVG documents, in a further subfolder like ``layer2.shapelayer/content.svg``. preview.png ~~~~~~~~~~~ An .kra file must have a ``preview.png`` in order to allow file browser software to render the thumbnail efficiently. It must be a non-interlaced PNG with 8 bits per channel of at most 256x256 pixels. It should be as big as possible without upscaling or changing the aspect ratio. Any aspect ratio is permitted. It should not contain any frame or decoration. The thumbnail file must not be referenced in any ``.xml`` file. Optional Files -------------- mergedimage.png ~~~~~~~~~~~~~~~ An .kra file can have a ``mergedimage.png`` in order to accommodate interoperability with viewer software and other application. It must contain the final rendered image without any frame or decoration. This file must be a PNG file with 8 or 16 bits per channel. Backup and -autosave files do not have a mergedimage.png/ +autosave files do not have a mergedimage.png. + +Layer Types +----------- + +Krita supports a number of layer and mask types. + +As shown in the example section, there's several bits of data that makes up a stored layer in Krita. + +The first part is it's entry in the maindoc.xml. This is where things like visibility and layer blending mode are stored, as well as the position of the layer inside the layer stack. + +colorlabel + An integer determining the color label. +x + The x offset in pixels. +y + The y offset in pixels +onionskin + Whether or not onionskins are enabled. +filename + References the main file in the layer folder that holds the pixeldata or svg data of this layer. +locked + Whether or not editing is enabled. +collapsed + Whether or not child layers are visible in the docker. +opacity + The opacity of the layer, running from 0 to 255 +compositeop + The composite operation, or blending mode of the layer +nodetype + The type of layer a given layer is. +name + The label assigned to this layer inside the layer docker. this is not unique. +colorspacename + The model of the colorspace. +visible + Whether or not the layer is visible. +selected + Whether the layer was selected upon save. +uuid + The unique identifier of this layer. Should always be unique. +intimeline + Whether or not the layer is visible in the timeline. +channelflags + Which channels are enabled. +channellockflags + Which channels are locked for editing. +keyframes + The filename of the keyframes + + +The second part is the + +Raster based layers +~~~~~~~~~~~~~~~~~~~ + +These include paint layers, transparency masks, selection masks, colorize masks and yes, filter layers, filter masks and fill layers. + +Of these, only paint and colorize masks have pixel data in multiple channels, with the maximum amount of color channels being five, for CMYKA. For the other layers, the main pixeldata is the single-channel alpha color model, which determines where the mask or layer is active. These single channel layers will not have an associated icc profile embedded, but will have a defaultpixel file. + +For filter layers, filter masks, and fill layers, the filter itself is stored as an xml configuration with the suffix 'filterconfig'. + +Within the maindoc.xml, masks are always children of regular layer types. + +:: + + + + + + + +With colorize masks, there's a seperate folder (mask#.colorizemask) holding all the layer data stored for each guidance color stroke (named 'keystroke_#') as well as the total calculated result of the colorize mask. Furthermore, there is a configuration file stored in the content.xml, sorting the strokes. Mask specific settings are in maindoc.xml +:: + + + + + + + +use-edge-detection + whether or not to use edge detection. +limit-to-device + whether or not to limit the colorize area to the total layer size instead of the full canvas size. +cleanup + strength of the cleanup. +show-coloring + Whether or not the result is shown, corresponds to 'show output' in the ui. +edgedetectionsize + strength of the edgedetection filter. +edit-keystrokes + whether or not the editing of keystrokes is available. +fuzzy-radius + corresponds to gap-close-hint. + +The configuration file looks as follows: +:: + + + + + + + + + +Vector Layers +~~~~~~~~~~~~~ + +Vector layers are SVG files, which largely conform to the SVG 1.1 standard. + +The following items are unique to Krita: + +- something something markers. + + +Group Layers +~~~~~~~~~~~~ + +Group layers are groupings of other layers. They therefore only exist in the xml. + +code:: + + + + + + + + + + + +In the above xml, there is a group layer named 'shading', which has three paintlayers and a filter layer on top. + +Clone Layers +~~~~~~~~~~~~ + +Clone layers intended to be instances of other layers. Therefore, clone layers only exist inside the maindoc.xml. + +code:: + + + +clonefrom + name of the layer to cloen from. +clonetype + ??? +clonefromuuid + the unique identifier of the layer to clone from. + +File Layers +~~~~~~~~~~~ + + +Transform Masks +~~~~~~~~~~~~~~~ + + +Guides, grids, assistants and other side info. +---------------------------------------------- + +Grids +~~~~~ + +Only exist inside the maindoc.xml. + +:: + + + + + + + + + + + +Animation +~~~~~~~~~ + +In the maindoc.xml, the total length of animation is stored: + +:: + + + + + + + +framerate + the fps. +range + the range of the active animation area. +currentTime + the selected frame upon save. + +With the exception of the colorize mask, each of the raster based layers can have animation keyframes, which can be of the frame-by-frame type or the animation curves type (opacity only in this case). In both cases, there will be a layername.keyframes.xml file in the layers folder, which is referenced inside the maindoc.xml with the keyframes attribute: + +:: + + +The keyframes.xml file will look something like this: + +:: + + + + + + + + + + + + + + + -- snip -- + + + + + + + + + + + + + + + + + + + + + +time + the frame at which a given keyframe is placed. +color-label + the color of the frame. This is the exact same list as the regular layer color labels, and these are often used to mark important parts of the animation. +frame + the frame data file that a 'content' channel is pointing at. Note how the first frame points at the regular layer data, but subsequent frames are suffixed with 'f#' . +offset + unique frame x/y offset. This gets added on top of the layer offset. + +Animation curves are drawn from keyframe to keyframe. They can be visualized as having the time as the x-axis value and value as the y-axis value. The left and right tangent are then the extra nodes used for interpolation, in this case using bezier. + +Assistants +~~~~~~~~~~ + + +:: + + + + + +An assistant file will be stored under the assistants folder, and will look something like this: + +:: + + + + + + + + + + + +Guides +~~~~~~ + +:: + + + + + + + + + + + + + + + + + + + + + +Proofing +~~~~~~~~ + +:: + + + + -- snip layers -- + + + + + + + +The proofing profile will be stored inside the annotations/proofing folder. + +Layerstyles +~~~~~~~~~~~ + +:: + + +The layerstyles themselves will be stored inside the layerstyles.asl file, in the annotations folder. + +Other +~~~~~ + +Projection background: + +:: +