wip: masking

Author: f0e

README.md

@@ -87,6 +87,19 @@ Using blur on 60fps footage results in clean motion blur, but occasionally leave
 
 If your footage contains duplicate frames then occasionally blurred frames will look out of place, making the video seem unsmooth at points. The 'deduplicate' option will automatically fill in duplicated frames with interpolated frames to prevent this from happening.
 
+### Masks
+
+Interpolation has no idea that a HUD isn't part of the scene, so it warps static overlays - crosshairs, killfeeds, timers - along with the world behind them. A mask marks those regions so they keep their original pixels instead.
+
+Masks are png files kept in the `masks` folder of your config folder. White means "interpolate this as normal", black means "leave this alone". Anything in between blends the two.
+
+Pick one with the `mask` config setting to apply it to everything by default, and override it per clip from the dropdown in the queue - so a Counter-Strike mask and a Fortnite mask can be used on different clips in the same batch. `blur-cli` takes a `--mask` argument for the same thing (`--mask none` turns off a mask set in the config).
+
+Two things worth knowing:
+
+- Masked areas still get motion blur. Only interpolation skips them, so they blend like the rest of the video.
+- The mask is scaled to fit the video, so one mask works across resolutions as long as the aspect ratio matches.
+
 ### Frameserver output
 
 Blur supports rendering from frameservers. This means you can avoid having to run blur on your input videos when video editing. When rendering, simply output (make sure your project is high framerate) to the frameserver and then drag the generated AVI into blur. Note that some video editing software might limit the maximum project framerate.
@@ -113,6 +126,7 @@ Blur supports rendering from frameservers. This means you can avoid having to ru
 
 - interpolate - whether or not the input video file will be interpolated to a higher fps
 - interpolated fps - if interpolate is enabled, this is the fps that the input file will be interpolated to (before blurring). can be a set fps number or a multiplier (append x to end e.g. `5x`)
+- mask - mask image used to protect parts of the frame from interpolation, or `none`. [see masks](#masks)
 - interpolation method - method used for interpolation:
   - Quality: RIFE > svp
   - Speed: svp > RIFE

src/cli/cli.cpp

@@ -1,13 +1,15 @@
 #include "cli.h"
 #include "common/rendering.h"
+#include "common/masks.h"
 
 bool cli::run(
 	std::vector<std::filesystem::path> inputs,
 	std::vector<std::filesystem::path> outputs,
 	std::vector<std::filesystem::path> config_paths,
 	bool preview,
 	bool verbose,
-	bool disable_update_check
+	bool disable_update_check,
+	const std::string& mask
 ) {
 	auto init_res = blur.initialise(verbose, preview);
 	if (!init_res) { // todo: preview in cli
@@ -81,8 +83,21 @@ bool cli::run(
 				std::filesystem::create_directories(parent);
 		}
 
+		std::optional<std::string> mask_override;
+		if (!mask.empty()) // "none" turns off a mask the config sets, for this run only
+			mask_override = mask == masks::NONE_OPTION ? "" : mask;
+
 		auto add_res = rendering::video_render_queue.add(
-			input_path, video_info, config_path, config_app::get_app_config(), output_path
+			input_path,
+			video_info,
+			config_path,
+			config_app::get_app_config(),
+			output_path,
+			0.f,
+			1.f,
+			{},
+			{},
+			mask_override
 		);
 
 		if (add_res.error) {

src/cli/cli.h

@@ -7,6 +7,9 @@ namespace cli {
 		std::vector<std::filesystem::path> config_paths,
 		bool preview,
 		bool verbose,
-		bool disable_update_check = false
+		bool disable_update_check = false,
+
+		// mask filename to render every input with. empty leaves each config's own mask alone
+		const std::string& mask = ""
 	);
 }

src/cli/main.cpp

@@ -32,10 +32,14 @@ int main(int argc, char* argv[]) {
 	std::vector<PathStr> config_path_strs;
 	bool preview = false;
 	bool verbose = false;
+	std::string mask;
 
 	app.add_option("-i,--input", input_strs, "Input file name(s)")->required();
 	app.add_option("-o,--output", output_strs, "Output file name(s) (optional)");
 	app.add_option("-c,--config-path", config_path_strs, "Manual configuration file path(s) (optional)");
+	app.add_option(
+		"--mask", mask, "Mask image filename in the masks folder, or 'none' to disable one set in the config (optional)"
+	);
 	app.add_flag("-p,--preview", preview, "Enable preview");
 	app.add_flag("-v,--verbose", verbose, "Verbose mode");
 
@@ -45,7 +49,7 @@ int main(int argc, char* argv[]) {
 	auto outputs = to_paths(output_strs);
 	auto config_paths = to_paths(config_path_strs);
 
-	cli::run(inputs, outputs, config_paths, preview, verbose);
+	cli::run(inputs, outputs, config_paths, preview, verbose, false, mask);
 
 	return 0;
 }

src/common/blur.cpp

@@ -6,6 +6,7 @@
 #include "config_blur.h"
 #include "config_app.h"
 #include "config_presets.h"
+#include "masks.h"
 
 tl::expected<void, std::string> Blur::initialise(bool _verbose, bool _using_preview) {
 	resources_path = u::get_resources_path();
@@ -23,6 +24,10 @@ tl::expected<void, std::string> Blur::initialise(bool _verbose, bool _using_prev
 	if (!std::filesystem::exists(preset_config_path))
 		config_presets::create(preset_config_path, PresetSettings{});
 
+	// so there's somewhere to drop mask images even before one's been used
+	std::error_code masks_ec;
+	std::filesystem::create_directories(masks::get_path(), masks_ec);
+
 #if defined(_WIN32)
 	used_installer = std::filesystem::exists(resources_path / "lib\\vapoursynth\\vspipe.exe") &&
 	                 std::filesystem::exists(resources_path / "lib\\ffmpeg\\ffmpeg.exe");

src/common/config_blur.cpp

@@ -38,6 +38,9 @@ std::string config_blur::generate_config_string(const BlurSettings& settings, bo
 		if (!concise || settings.interpolate) {
 			output << "interpolated fps: " << settings.interpolated_fps << "\n";
 			output << "interpolation method: " << settings.interpolation_method << "\n";
+			if (!concise || !settings.mask.empty()) {
+				output << "mask: " << settings.mask << "\n";
+			}
 		}
 	}
 
@@ -300,6 +303,7 @@ BlurSettings config_blur::parse_from_map(const std::map<std::string, std::string
 	config_base::extract_config_value(config_map, "interpolate", settings.interpolate);
 	config_base::extract_config_value(config_map, "interpolated fps", settings.interpolated_fps);
 	config_base::extract_config_value(config_map, "interpolation method", settings.interpolation_method);
+	config_base::extract_config_value(config_map, "mask", settings.mask);
 
 	config_base::extract_config_value(config_map, "pre-interpolate", settings.pre_interpolate);
 	config_base::extract_config_value(config_map, "pre-interpolated fps", settings.pre_interpolated_fps);
@@ -446,6 +450,7 @@ tl::expected<nlohmann::json, std::string> BlurSettings::to_json() const {
 	j["interpolate"] = this->interpolate;
 	j["interpolated_fps"] = this->interpolated_fps;
 	j["interpolation_method"] = this->interpolation_method;
+	j["mask"] = this->mask;
 
 	j["pre_interpolate"] = this->pre_interpolate;
 	j["pre_interpolated_fps"] = this->pre_interpolated_fps;

src/common/config_blur.h

@@ -48,6 +48,10 @@ struct BlurSettings {
 	std::string interpolation_method = "svp";
 #endif
 
+	// filename of a png in <settings path>/masks, or empty for none. masks protect regions from
+	// interpolation, so this does nothing when interpolate is off
+	std::string mask;
+
 	bool pre_interpolate = false;
 	std::string pre_interpolated_fps = "360";
 	std::string pre_interpolation_method = "rife";

src/common/masks.cpp

@@ -0,0 +1,38 @@
+#include "masks.h"
+
+std::filesystem::path masks::get_path() {
+	return blur.settings_path / FOLDER_NAME;
+}
+
+std::vector<std::string> masks::list() {
+	std::vector<std::string> masks;
+
+	auto path = get_path();
+
+	std::error_code ec; // don't throw if the folder's missing or unreadable, just show nothing
+	for (const auto& entry : std::filesystem::directory_iterator(path, ec)) {
+		if (!entry.is_regular_file(ec))
+			continue;
+
+		if (u::to_lower(u::path_to_string(entry.path().extension())) != ".png")
+			continue;
+
+		masks.push_back(u::path_to_string(entry.path().filename()));
+	}
+
+	std::ranges::sort(masks);
+
+	return masks;
+}
+
+std::vector<std::string> masks::options(const std::string& current) {
+	auto mask_files = list();
+
+	std::vector<std::string> options = { NONE_OPTION };
+	options.insert(options.end(), mask_files.begin(), mask_files.end());
+
+	if (!current.empty() && !u::contains(options, current))
+		options.push_back(current);
+
+	return options;
+}

src/common/masks.h

@@ -0,0 +1,25 @@
+#pragma once
+
+// Masks mark regions of the frame that should be protected from interpolation. The interpolator has no idea
+// that a HUD isn't part of the scene, so it warps it along with the world behind it; a mask lets the renderer
+// put the pre-interpolation pixels back over those regions afterwards.
+//
+// A mask is a png in <settings path>/masks - white where the frame should be interpolated as normal, black
+// where it should be left alone. Settings store the bare filename, so a config stays portable between
+// machines, and blur.py resolves it against the settings path it's already given.
+namespace masks {
+	inline const std::string FOLDER_NAME = "masks";
+
+	// shown in the mask dropdowns, and what an empty setting means
+	inline const std::string NONE_OPTION = "none";
+
+	std::filesystem::path get_path();
+
+	// filenames of every png in the masks folder, sorted. empty if the folder doesn't exist
+	std::vector<std::string> list();
+
+	// what a mask dropdown shows: "none", then every mask in the folder. `current` is kept in the list even if
+	// it's been deleted since it was picked, so that's visible instead of the dropdown silently snapping to
+	// something else
+	std::vector<std::string> options(const std::string& current);
+}

src/common/rendering/render_queue.cpp

@@ -58,7 +58,8 @@ rendering::QueueAddRes rendering::VideoRenderQueue::add(
 	const std::function<void(
 		const VideoRenderDetails& render,
 		const tl::expected<rendering::RenderResult, std::variant<std::string, RenderError>>& result
-	)>& finish_callback
+	)>& finish_callback,
+	const std::optional<std::string>& mask_override
 ) {
 	// parse config file (do it now, not when rendering. nice for batch rendering the same file with different
 	// settings)
@@ -67,6 +68,9 @@ rendering::QueueAddRes rendering::VideoRenderQueue::add(
 		!config_path.has_value() // use global only if no config path is specified
 	);
 
+	if (mask_override)
+		config_res.config.mask = *mask_override;
+
 	if (!video_info.audio_sample_rates.empty() && detail::copies_audio(config_res.config, app_settings)) {
 		if (auto conflict = detail::get_audio_copy_conflict(config_res.config, start != 0.f || end != 1.f)) {
 			return {