Repository navigation
Multifilter
The multifilter is a pre-transform plugin, which means that it acts on tablet coordinates. For the average user's case, it should apply after other pre-transform plugins that depend more on the tablet's raw data. The plugin is asynchronous internally, but by default the Interpolation setting is disabled, which makes it act like a synchronous plugin.
Apart from the settings that appear, the plugin can also read a configuration file with a few extra options.
The filter will intentionally overshoot in a way that reverses EMA smoothing with a weight of this setting, similar to Reconstructor. If you know you need to use this setting, but don't know what setting to use, check Reconstuctor's guide.
The difference that this setting's functionality has from Reconstructor is that the internal reverse EMA value that was originally the setting transitions from 1 when not moving to the setting's value when moving. If a Gaomon S620* is detected and the user is hovering, the filter becomes more conservative in its transition as the tablet's firmware filtering becomes more aggressive.
The filter will simply apply the weight on top of the weight created by Distance Smoothing.
This setting is used in the AEMA function, the input for which is always the output of the RF function. This setting interacts with the Distance Smoothing setting, as when the movement goes from 0 to the separation threshold, the output will shift to the input by the stock weight multiplied by however much the movement is compared to the separation threshold. Because of this, the effect of this setting is actually different from just simple EMA, which will be fixed in the next update.
The filter creates a deadzone that is the size of the setting. When the input is inside of the deadzone, the deadzone and output will not move. When it moves outside the deadzone, the deadzone and output move separately.
This setting is used in the RF function, the input for which is whatever points are being filtered (by default, the output of the last filter that applied, or the raw tablet data if there are none). This deadzone's behavior is somewhat similar to the function seen in Radial Follow, but there are two major differences:
- The output (in most cases) moves towards the input as the cursor moves, recovering the deadzone's natural distance delay, where in Radial Follow the deadzone and the output are one and the same (assuming inner radius is being used).
- By default, the movement behavior is such that even if there is a significant difference between the direction the user's pen is moving and the direction between the deadzone and the input, the deadzone and output will move in the same direction as the input. This makes it so it's possible to make a sharp right angle with your pen using a large deadzone, which isn't possible with a normal follow radius.
Currently, when a fast move is made in this manner, especially with a large setting (~above 50), the deadzone may not recover as expected. For example, going right then quickly going straight down will end up keeping the deadzone's location mostly to the right, when the deadzone is expected to end up above the input. This will be changed in the next update.
The filter will create a smoothing weight based on the distance from its input to its own output.
This setting is used in the AEMA function. Its weight is based on the proportion of input-output distance raised to a power, which is 2 by default but can be changed in the config file. This is multiplied by Separated Threshold Mult to create the movement threshold needed to lerp the output to the recovery point.
The default movement threshold for smoothing separation is set to the Distance Smoothing value, and this multiplies it. A lower setting causes a more aggressive recovery. This setting is internally clamped so that it cannot go below 0.5.
This setting is used in the AEMA function. It's used to create the separation scale, which is a smoothstep of input-output distance from 0 to the distance smoothing setting multiplied by this setting. When wired-interpolation filtering is being used, the scale is only updated if the update's deltaTime is greater than the expected time times 0.99.
This uses an EMA weight that is usually 1, which makes it do nothing, but when a sharp rise in acceleration is detected, the weight quickly approaches 0, and slowly recovers.
This setting is used in the AEMA function, but operates after all other internal filter functions, so its input is the output of the smoothing part of the AEMA function. The sensitivity of this part of the filter can be changed with Area Scale, and its behavior can be changes to be less aggressive with multiple settings in the config file. Currently, the base transition between full locking and forced recovery is between an input-output distance of 500 and 3500, which is extremely aggressive, but it will be changed to 250 and 1000 in the next update.
The most important use of this setting appears in accel response, where it multiplies thresholds.
The other uses of this setting appears in a few cases in prediction.
Compensates for the usual tablet/display aspect ratio discrepancy seen in most osu! player's settings.
Internally multiplies the X value of the plugin's input positions by the setting, then at output divides the output by the setting. May not even be noticeable in normal cases.
Looks for a configuration file in a specific location for your tablet. For example, if you had a Wacom PTK-470, the OpenTabletDriver.Daemon executable is located at "Drive/Users/You/OpenTabletDriver/OpenTabletDriver.Daemon", your file would be located at "Drive/Users/You/OpenTabletDriver/SaturnConfig/Wacom PTK-470.json". Upon startup, there will be a log line indicating to you that the file was loaded successfully.
The file is formatted like this
{
"setting1": 4,
"setting2": True,
"setting3": 4
}
where the last setting does not have a comma after it. The settings will be listed at the bottom of this page.
Uses a similar approach to Temporal Resampler. You shouldn't enable this with an unusually high report rate unless you know what you are doing.
Quadratically interpolates between the last 2 interpolation points depending on the location of the 3rd interpolation point and the expected time to the next report, which on lower report rate tablets works decently to model motion. If an unusually high report rate is detected, the interpolation becomes linear between the last 2 interpolation points based on the expected time to the next report.
This only applies if Interpolation is enabled, and it changes whether or not the filter outputs exactly when it catches a report, and decides whether to apply filtering on the interpolation's output or the points to be interpolated.
Interpolators, if not told to, will not output anything the moment they catch a report, instead opting to only update the data that is used when updating at the set frequency, but calling the UpdateState function (runs at frequency) within the ConsumeState function (runs at tablet report) the being enabled will force the filter to output when it gets an input.
This setting also decides what points to filter when interpolating: the points that are to be interpolated between, or the base output of the unfiltered interpolation. Choosing to filter the interpolation's output is more well received according to the few people who have told me something about this.
This modifies the points to be interpolated between. By the nature of interpolation, trying to predict 1 report ahead does not mean attempting to take the cursor ahead of where it really is.
The approach used is a modified version of what happens in Temporal Resampler. It's more sensitive to noise but reacts to sharp acceleration far better. There can be changes made based on the tablet in use, but a very high report rate being detected will revert the changes.
The default setting values can be found in this file. More settings will be added to make the function of the multifilter more malleable to a power user.
To enable: "HoverSettingsEnabled": True
and include EVERY hover setting. The filter will switch between using the hover settings and drag settings (your usual settings) based on pen pressure. If you disable pen pressure, the hover settings will always apply.
The curve of a time scale is (1 - ((1-x)^b)), where x is the starting weight and b is the time scale. If the time scale is 2, the adjusted weight will be the same as if the starting weight was applied twice at the same time.
These raise their own calculated weights to powers. This leaves out a bit of information, but that is basically what they do. If your tablet has a high report rate and you use accel response, you may see a visual smoothness benefit from changing the accel response power from 3 to 4.
The inner threshold should always be smaller than the outer threshold. This decides the distance lock used when the pen is under sharp acceleration.
These should likely not be changed unless you know what you are doing. RecoveryLimit dictates the point between deadzone and input that the RF function's output approaches with movement. UseDirectionForClamping enables the inner radius behavior improvement that is described above in the second bullet point.
DisableTabletTweaks makes it so there is no attempt to change behavior based on your tablet.
VecMatMul only applies when prediction is being used, and switches to AVX/FMA x86 intrinsics for 4x4 matrix multiplication if the CPU is a modern x86 chip that has these instructions. (written by an LLM but it's a common way to do it seen elsewhere)
Movement Scaling lets you use your own movement logic for scaling settings (like Inner Radius or Stock Weight). MovementScalingWindow decides the amount of reports that are used when calculating movement. For example, if it is set to 2, velocity will be evaluated as the gap between the current report and the last last report. ScaleSettingByMovement is a bitmask. Here's a pseudocode-ish representation of some of the logic because I can't put it any better.
context: w is MovementScalingWindow, settingmask is your ScaleSettingByMovement value.
the movementnumbers available are:
velocity term = (pos[0] - pos[w]).Length()
accel term = velocity term - (pos[w] - pos[w * 2]).Length()
jerk term = accel term - ((pos[w * 2] - pos[w * 3]).Length() - (pos[w * 3] - pos[w * 4]).Length())
1: movement value = velocity term
2: movement value = accel term
4: movement value = jerk term
8: movement value = abs(accel term)
16: movement value = accel term + abs(jerk term)
32: movement value = abs(accel term) + abs(jerk term)
if you don't know what a bitmask is, the powers of 2 are represented with a single 1 in their value: 1 is 0001b, 2 is 0010b, 4 is 0100b, so on.
Just checking for these makes it so you can just add these values together to combine them,
never using the same number twice, so if you wanted to use velocity and the absolute value of acceleration,
you would add 1+8 to get 9, which you would put as your desired ScaleSettingByMovement value.
for every movementnumber,
if settingmask & movementnumber == movementnumber, (fulfilled by 1 and 8 when settingmask is 9)
multiply setting by a value ranging from setting start mult to setting end mult,
based on the smoothstep of the chosen movement value from chosen movement start threshold to chosen movement end threshold.
Example:
In config file:
{
"MovementScalingWindow" : 4,
"ScaleInnerRadiusByMovement" : 4,
"StartJerkThreshold" : 0.0,
"EndJerkThreshold" : 50.0,
"StartInnerRadiusMult" : 0.5,
"EndInnerRadiusMult" : 1.5
}
Let's say the inner radius setting is 25.0.
What will happen:
As (ScaleInnerRadiusByMovement & (power of 2 from 1 to 32) == (power of 2 from 1 to 32)) is only equal to 4,
only jerk will be used to scale.
Jerk term is evaluated to be
((pos[0] - pos[4]).Length() - (pos[4] - pos[8]).Length()) -
((pos[8] - pos[12]).Length() - (pos[12] - pos[16]).Length()).
Let's say it evaluates to 35.0.
Now the inner radius value to be used for now until the next report is:
(25.0) * double.Lerp(0.5, 1.5, Smoothstep(35.0, 0.0, 50.0))
Smoothstep (graph of this case) returns 0 when the first value is the second value or beyond, 1 when the first value is the third value or beyond, and a smooth transition from 0 to 1 between them. We get about 0.784, so the Lerp function evaluates to 0.5 + 0.784 * (1.5 - 0.5), which cleanly becomes 1.284. This multiplies our base value, so for this report our inner radius value is 25 * 1.284 or 32.1.