Documented the animation optimization feature.

Author: Nusiq

animation-optimization-visualization.ipynb

@@ -1,3 +1,4 @@
+(creating-animations-from-scratch)=
 # Creating animations from scratch
 
 In this section, you will learn how to create animations in Mcblend from scratch. It is assumed that the reader already knows how to make and export models in Mcblend. We will start with a simple model that has a single bone and a single cube connected to it.

docs/animations/creating_animations_from_scratch.md

@@ -14,6 +14,7 @@ The editor on the left side of the screen is the `Nonlinear Animation` editor. T
 
 During the export process, the exported data for animations is not solely based on the NLA tracks. Mcblend exports the same animation that is visible in the 3D viewport during the preview, which can be affected by various factors such as constraints, inverse kinematics, and physics. This means that some bones in the model may not be animated in the NLA tracks, but they will be animated in the exported animation due to the influence of other factors that affect their movement. The keyframe times for the animations are based on the keyframe times in the NLA tracks, but not at the bone level. Essentially, if there is any keyframe at a certain time, Mcblend compares the pose of the entire model at that time to the pose of the model at the previous keyframe. If the pose is different for a given bone, Mcblend will add a keyframe for that bone to the exported animation. Any pose changes that occur between keyframes are not checked, which can lead to unexpected results, particularly when using physics, which often generates complex movement that requires many keyframes to be animated correctly.
 
+(stepped-linear-smooth-animations)=
 ## Stepped, Linear, and Smooth Interpolation
 
 Minecraft supports three types of frames: stepped, linear, and smooth. Blender offers corresponding interpolation modes: constant, linear, and Bézier.

docs/animations/essential_concepts.md

@@ -1,3 +1,4 @@
+(exporting-animations)=
 # Exporting Animations
 
 This section explains how to export animations from Mcblend and mentions some additional settings that can be configured before exporting.
@@ -8,4 +9,6 @@ Before exporting the animation, you can configure some additional settings in th
 
 The `Override previous animation`, `Loop`, and `Anim Time update` settings are properties of Minecraft animations and are directly exported to the file. They have no effect on Mcblend. The `Frame start` and `Frame end` settings determine the range of frames that will be exported to the animation.
 
-Exporting the animation is similar to exporting a model, as explained in the ["Creating animations from scratch"](/animations/creating_animations_from_scratch) documentation page. Simply go to `File > Export > Export Bedrock Animation` and select the export path.
+The `Optimize Animation` checkbox allows you to apply **lossy** optimization to the animation during export. This option also lets you configure the error acceptable margin for the optimization. More details in {ref}`Optimizing animations<optimizing-animations>` section.
+
+Exporting the animation is similar to exporting a model, as explained in the {ref}`Creating animations from scratch<creating-animations-from-scratch>` documentation page. Simply go to `File > Export > Export Bedrock Animation` and select the export path.

docs/animations/exporting_animations.md

@@ -0,0 +1,28 @@
+(optimizing-animations)=
+# Optimizing Animations
+When making animations with Mcblend, you often end up baking some parts of the animation especially when transformations in the animations are driven by something else (physics simulation, inverse kinematics etc.). Minecraft animation storage format is not designed to reduce the size so the animations that use a lot of keyframes often end up being very large.
+
+To counteract this, Mcblend provides an option to optimize the animation during export.
+
+**TL;DR:** In order to optimize the animation, you need to select the `Optimize Animation` checkbox in the `Object Properties` panel under the `Mcblend: Animations` tab and set the `Error margin` to a value that is appropriate for your animation. Bigger values will result in smaller files but will also result in less accurate animations. Smaller values will result in larger files but will also result in more accurate animations.
+
+```{warning}
+The animation optimization works **only for the linear keyframes**. You can read more about the interpolation modes in the {ref}`Stepped, Linear, and Smooth Interpolation<stepped-linear-smooth-animations>` section.
+```
+
+## How does it work?
+
+The optimization algorithm used by Mcblend is really simple. Mcblend loops through all keyframes and checks if interpolating between the previous and next keyframe is close enough to the current keyframe. If it is, the current keyframe is removed.
+
+![](/img/animations/animation-optimization-how-it-works.svg)
+
+The `Error margin` is defined as the ratio between the distance moved from current keyframe and its interpolated alternative (`a`) to the distance moved from the previous keyframe to the next keyframe (`b`). In the picture you can see that as `error=a/b`.
+
+### Examples
+Examples below show how different levels of optimization affect the graph of the animation.
+
+![](/img/animations/animation-optimization-example-raw.svg)
+![](/img/animations/animation-optimization-example-4pct.svg)
+![](/img/animations/animation-optimization-example-10pct.svg)
+
+

docs/animations/optimizing_animations.md

@@ -39,6 +39,7 @@ Fix invalid UV mapping<texturing_and_uv_mapping/fixing_invalid_uv_mapping>
 Essential concepts for creating animations in Mcblend <animations/essential_concepts>
 Creating animations from scratch <animations/creating_animations_from_scratch>
 Exporting animations <animations/exporting_animations>
+Optimizing animations <animations/optimizing_animations>
 Animating sound and particle effects <animations/animating_sound_and_particle_effects>
 Physics simluation <animations/physics_simulation>
 ```