focalpy 0.0.1__tar.gz

focalpy-0.0.1/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

focalpy-0.0.1/.github/workflows/wheels.yml

@@ -0,0 +1,69 @@
+name: Wheels
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build_wheels:
+    name: wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # macos-14 is arm64 and cross-compiles the x86_64 wheel too (see
+        # [tool.cibuildwheel.macos] archs). GitHub retired the Intel macos-13
+        # runners, so requesting one queues forever.
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-14, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # Pin this to an exact version once you have a build you trust.
+      - run: python -m pip install "cibuildwheel>=2.20"
+
+      # Config lives in [tool.cibuildwheel] in pyproject.toml. Because the
+      # extension is abi3, this builds cp312 only and the result covers every
+      # later Python.
+      - run: python -m cibuildwheel --output-dir wheelhouse
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  make_sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: pipx run build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: publish to PyPI
+    needs: [build_wheels, make_sdist]
+    runs-on: ubuntu-latest
+    # Only on a version tag: git tag v0.0.2 && git push --tags
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      # Trusted publishing: PyPI verifies this workflow via OIDC, so there is
+      # no API token to store. Register the repo at
+      # https://pypi.org/manage/account/publishing/ first.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

focalpy-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+build/
+dist/
+*.egg-info/
+__pycache__/
+*.so
+.pytest_cache/
+compile_commands.json
+.DS_Store

focalpy-0.0.1/CMakeLists.txt

@@ -0,0 +1,48 @@
+cmake_minimum_required(VERSION 3.26)
+project(focal LANGUAGES CXX VERSION 0.0.1)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)   # for clangd / IDE tooling
+
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
+endif()
+
+# The C++ library.  Globbed with CONFIGURE_DEPENDS so new files under src/
+# get picked up without editing this file.
+file(GLOB_RECURSE FOCAL_SOURCES CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp")
+add_library(focal_core STATIC ${FOCAL_SOURCES})
+target_include_directories(focal_core PUBLIC
+  "${CMAKE_CURRENT_SOURCE_DIR}/include"
+  "${CMAKE_CURRENT_SOURCE_DIR}/third_party")
+target_compile_options(focal_core PRIVATE
+  $<$<CXX_COMPILER_ID:AppleClang,Clang,GNU>:-Wall -Wextra>)
+
+if(MSVC)
+  # windows.h (pulled in by stb under STBI_WINDOWS_UTF8) defines min/max as
+  # macros, which breaks std::min and std::max at every call site.  stb also
+  # uses fopen/sprintf, which MSVC flags as deprecated.
+  target_compile_definitions(focal_core PRIVATE NOMINMAX _CRT_SECURE_NO_WARNINGS)
+endif()
+
+# The Python extension module.
+# Development.SABIModule is what nanobind links against for STABLE_ABI below;
+# without it the STABLE_ABI flag is silently ignored and you get one wheel per
+# Python version instead of one per platform.
+find_package(Python 3.12 REQUIRED
+             COMPONENTS Interpreter Development.Module Development.SABIModule)
+
+execute_process(
+  COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+  OUTPUT_VARIABLE NANOBIND_CMAKE_DIR OUTPUT_STRIP_TRAILING_WHITESPACE
+  COMMAND_ERROR_IS_FATAL ANY)
+list(APPEND CMAKE_PREFIX_PATH "${NANOBIND_CMAKE_DIR}")
+find_package(nanobind CONFIG REQUIRED)
+
+file(GLOB_RECURSE FOCAL_BINDINGS CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/python/*.cpp")
+nanobind_add_module(_focal STABLE_ABI NB_STATIC ${FOCAL_BINDINGS})
+target_link_libraries(_focal PRIVATE focal_core)
+
+install(TARGETS _focal LIBRARY DESTINATION focal)

focalpy-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edison Sun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

focalpy-0.0.1/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: focalpy
+Version: 0.0.1
+Summary: Image processing in C++ with a zero-copy NumPy interface
+Keywords: image-processing,imaging,computer-vision,numpy,cpp
+Author-Email: Edison Sun <edisonsun31@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Project-URL: Homepage, https://github.com/edisons3608/focal
+Project-URL: Repository, https://github.com/edisons3608/focal
+Project-URL: Issues, https://github.com/edisons3608/focal/issues
+Requires-Python: >=3.12
+Requires-Dist: numpy>=1.23
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: scipy; extra == "test"
+Requires-Dist: scikit-image; extra == "test"
+Requires-Dist: pillow; extra == "test"
+Description-Content-Type: text/markdown
+
+# focal
+
+Image processing in C++20 with a zero-copy NumPy interface.
+
+```python
+import focal
+
+img = focal.imread("photo.jpg")          # linear float32, (h, w, c)
+img = focal.exposure(img, 0.5)           # half a stop brighter
+img = focal.gaussian_blur(img, 2.0)
+focal.imwrite("out.png", img)            # encodes back to sRGB
+```
+
+## Design
+
+**Everything is a view.** The core type is a non-owning `{pointer, dtype, shape,
+strides}` struct, so a crop, a single channel, and a NumPy array handed over
+from Python are all the same type, and none of them copy. Strides are in bytes,
+matching NumPy exactly, so wrapping an incoming array is copying six integers.
+
+**Nothing converts silently.** Array arguments are declared `.noconvert()`, so
+passing a float64 or non-contiguous array raises `TypeError` instead of quietly
+costing a full-size copy. Converting is the caller's decision.
+
+**Filtering happens in linear light.** `imread` decodes sRGB to linear float32
+and `imwrite` encodes back. Blurring or resizing gamma-encoded values darkens
+the result — on a synthetic test chart, a σ=3 blur done in gamma space came out
+29% darker than the same blur done correctly, with individual pixels off by
+74/255.
+
+## What's here
+
+| | |
+|---|---|
+| I/O | `imread`, `imwrite` — PNG, JPEG, BMP, TGA via stb |
+| Point ops | `gamma`, `exposure`, `brightness_contrast`, `invert`, `clip`, `blend`, `apply_lut` |
+| Filtering | `gaussian_blur` (separable) |
+| Sampling | `sample` — nearest and bilinear, border-aware |
+| Color | `srgb_to_linear`, `linear_to_srgb` |
+
+Border modes (`clamp`, `reflect`, `reflect101`, `wrap`, `constant`) are shared
+by every spatial op and match `scipy.ndimage`'s semantics.
+
+## Install
+
+```bash
+pip install focalpy
+```
+
+Building from source needs a C++20 compiler and CMake:
+
+```bash
+git clone https://github.com/edisons3608/focal
+cd focal
+pip install -e . --no-build-isolation
+pytest
+```
+
+## Status
+
+Early. The API will change. Tests compare against `scipy.ndimage` and `PIL`
+where an oracle exists.
+
+## License
+
+MIT. Bundles [stb](https://github.com/nothings/stb) (public domain).

focalpy-0.0.1/README.md

@@ -0,0 +1,66 @@
+# focal
+
+Image processing in C++20 with a zero-copy NumPy interface.
+
+```python
+import focal
+
+img = focal.imread("photo.jpg")          # linear float32, (h, w, c)
+img = focal.exposure(img, 0.5)           # half a stop brighter
+img = focal.gaussian_blur(img, 2.0)
+focal.imwrite("out.png", img)            # encodes back to sRGB
+```
+
+## Design
+
+**Everything is a view.** The core type is a non-owning `{pointer, dtype, shape,
+strides}` struct, so a crop, a single channel, and a NumPy array handed over
+from Python are all the same type, and none of them copy. Strides are in bytes,
+matching NumPy exactly, so wrapping an incoming array is copying six integers.
+
+**Nothing converts silently.** Array arguments are declared `.noconvert()`, so
+passing a float64 or non-contiguous array raises `TypeError` instead of quietly
+costing a full-size copy. Converting is the caller's decision.
+
+**Filtering happens in linear light.** `imread` decodes sRGB to linear float32
+and `imwrite` encodes back. Blurring or resizing gamma-encoded values darkens
+the result — on a synthetic test chart, a σ=3 blur done in gamma space came out
+29% darker than the same blur done correctly, with individual pixels off by
+74/255.
+
+## What's here
+
+| | |
+|---|---|
+| I/O | `imread`, `imwrite` — PNG, JPEG, BMP, TGA via stb |
+| Point ops | `gamma`, `exposure`, `brightness_contrast`, `invert`, `clip`, `blend`, `apply_lut` |
+| Filtering | `gaussian_blur` (separable) |
+| Sampling | `sample` — nearest and bilinear, border-aware |
+| Color | `srgb_to_linear`, `linear_to_srgb` |
+
+Border modes (`clamp`, `reflect`, `reflect101`, `wrap`, `constant`) are shared
+by every spatial op and match `scipy.ndimage`'s semantics.
+
+## Install
+
+```bash
+pip install focalpy
+```
+
+Building from source needs a C++20 compiler and CMake:
+
+```bash
+git clone https://github.com/edisons3608/focal
+cd focal
+pip install -e . --no-build-isolation
+pytest
+```
+
+## Status
+
+Early. The API will change. Tests compare against `scipy.ndimage` and `PIL`
+where an oracle exists.
+
+## License
+
+MIT. Bundles [stb](https://github.com/nothings/stb) (public domain).

focalpy-0.0.1/include/focal/border.hpp

@@ -0,0 +1,52 @@
+#pragma once
+
+#include <cstdint>
+
+namespace focal {
+
+// What happens when an op reads outside the image.  Every spatial op routes
+// its out-of-range reads through map_index() so they all agree about edges.
+//
+// For a 4-wide row `a b c d`, reading left of it gives:
+//   Clamp       a a a a | a b c d      (scipy: "nearest")
+//   Reflect     d c b a | a b c d      (scipy: "reflect")   edge sample doubled
+//   Reflect101  d c b   | a b c d      (scipy: "mirror")    edge sample not repeated
+//   Wrap        a b c d | a b c d      (scipy: "grid-wrap")
+//   Constant     -- out of range, caller substitutes a fill value
+enum class Border { Clamp, Reflect, Reflect101, Wrap, Constant };
+
+// Sentinel returned for Border::Constant when the index is outside the image.
+inline constexpr int64_t kOutOfBounds = -1;
+
+// Fold an arbitrary index into [0, n), or kOutOfBounds under Border::Constant.
+inline int64_t map_index(int64_t i, int64_t n, Border b) {
+  if (n <= 0) return kOutOfBounds;
+  if (i >= 0 && i < n) return i;
+  if (n == 1) return b == Border::Constant ? kOutOfBounds : 0;
+
+  switch (b) {
+    case Border::Clamp:
+      return i < 0 ? 0 : n - 1;
+
+    case Border::Reflect: {  // period 2n, edge sample repeated
+      const int64_t period = 2 * n;
+      int64_t k = ((i % period) + period) % period;
+      return k < n ? k : period - 1 - k;
+    }
+
+    case Border::Reflect101: {  // period 2n-2, edge sample not repeated
+      const int64_t period = 2 * n - 2;
+      int64_t k = ((i % period) + period) % period;
+      return k < n ? k : period - k;
+    }
+
+    case Border::Wrap:
+      return ((i % n) + n) % n;
+
+    case Border::Constant:
+      return kOutOfBounds;
+  }
+  return kOutOfBounds;
+}
+
+}  // namespace focal

focalpy-0.0.1/include/focal/buffer.hpp

@@ -0,0 +1,45 @@
+#pragma once
+
+#include <cstddef>
+#include <vector>
+
+#include "focal/view.hpp"
+
+namespace focal {
+
+// Owns pixels.  Ops never take a Buffer -- they take a View, so the same code
+// works on memory we allocated and on memory NumPy allocated.
+class Buffer {
+ public:
+  Buffer() = default;
+
+  Buffer(int64_t height, int64_t width, int64_t channels, Dtype dt)
+      : dtype_(dt),
+        height_(height),
+        width_(width),
+        channels_(channels),
+        storage_(static_cast<size_t>(height * width * channels *
+                                     dtype_size(dt))) {}
+
+  View view() {
+    return make_view(storage_.data(), dtype_, height_, width_, channels_);
+  }
+  ConstView view() const {
+    return make_view(storage_.data(), dtype_, height_, width_, channels_);
+  }
+
+  Dtype dtype() const { return dtype_; }
+  int64_t height() const { return height_; }
+  int64_t width() const { return width_; }
+  int64_t channels() const { return channels_; }
+  size_t size_bytes() const { return storage_.size(); }
+
+ private:
+  Dtype dtype_ = Dtype::F32;
+  int64_t height_ = 0;
+  int64_t width_ = 0;
+  int64_t channels_ = 0;
+  std::vector<std::byte> storage_;
+};
+
+}  // namespace focal

focalpy-0.0.1/include/focal/check.hpp

@@ -0,0 +1,44 @@
+#pragma once
+
+#include <stdexcept>
+#include <string>
+
+#include "focal/view.hpp"
+
+namespace focal {
+
+// Shared preconditions.  Ops call these once at the top, never per pixel.
+
+inline void check_f32(ConstView v, const char *who) {
+  if (v.dtype != Dtype::F32)
+    throw std::invalid_argument(std::string(who) +
+                                ": expected an F32 view; convert at the edges "
+                                "of the pipeline, not inside ops");
+}
+
+inline void check_same_shape(ConstView a, ConstView b, const char *who) {
+  if (a.height != b.height || a.width != b.width || a.channels != b.channels)
+    throw std::invalid_argument(std::string(who) + ": shape mismatch (" +
+                                std::to_string(a.height) + "x" +
+                                std::to_string(a.width) + "x" +
+                                std::to_string(a.channels) + " vs " +
+                                std::to_string(b.height) + "x" +
+                                std::to_string(b.width) + "x" +
+                                std::to_string(b.channels) + ")");
+}
+
+inline void check_channels(ConstView v, int64_t want, const char *who) {
+  if (v.channels != want)
+    throw std::invalid_argument(std::string(who) + ": expected " +
+                                std::to_string(want) + " channels, got " +
+                                std::to_string(v.channels));
+}
+
+// The last channel of a 2- or 4-channel image is alpha: a linear coverage
+// fraction, not a colour.  Tone curves and transfer functions must skip it.
+// io.cpp applies the same rule; keep them agreeing by using this.
+inline bool is_alpha_channel(int64_t channels, int64_t c) {
+  return (channels == 2 || channels == 4) && c == channels - 1;
+}
+
+}  // namespace focal

focalpy-0.0.1/include/focal/convert.hpp

@@ -0,0 +1,54 @@
+#pragma once
+
+#include <algorithm>
+#include <cstdint>
+
+#include "focal/buffer.hpp"
+#include "focal/view.hpp"
+
+namespace focal {
+
+// Normalization convention, decided once here so no op re-decides it:
+//   u8   255   <-> 1.0f
+//   u16  65535 <-> 1.0f
+//   f32  passthrough, unclamped
+// Values are clamped to [0, 1] on the way down into an integer type.
+
+inline float unit_from_u8(uint8_t v) { return v * (1.0f / 255.0f); }
+inline float unit_from_u16(uint16_t v) { return v * (1.0f / 65535.0f); }
+
+inline uint8_t u8_from_unit(float f) {
+  return static_cast<uint8_t>(std::clamp(f, 0.0f, 1.0f) * 255.0f + 0.5f);
+}
+inline uint16_t u16_from_unit(float f) {
+  return static_cast<uint16_t>(std::clamp(f, 0.0f, 1.0f) * 65535.0f + 0.5f);
+}
+
+// Read one sample as a unit float, whatever the view's dtype.  Used at the
+// edges of the library; ops themselves run on f32 views and skip this.
+inline float load_unit(ConstView v, int64_t y, int64_t x, int64_t c = 0) {
+  switch (v.dtype) {
+    case Dtype::U8:  return unit_from_u8(v.at<uint8_t>(y, x, c));
+    case Dtype::U16: return unit_from_u16(v.at<uint16_t>(y, x, c));
+    case Dtype::F32: return v.at<float>(y, x, c);
+  }
+  return 0.0f;
+}
+
+inline void store_unit(View v, int64_t y, int64_t x, int64_t c, float f) {
+  switch (v.dtype) {
+    case Dtype::U8:  v.at<uint8_t>(y, x, c) = u8_from_unit(f); break;
+    case Dtype::U16: v.at<uint16_t>(y, x, c) = u16_from_unit(f); break;
+    case Dtype::F32: v.at<float>(y, x, c) = f; break;
+  }
+}
+
+// Whole-image dtype conversion.
+Buffer convert(ConstView src, Dtype dst);
+
+// Decode integer sRGB to linear f32, and encode back.  These are the two calls
+// that belong at the very edges of a pipeline.
+Buffer srgb_to_linear_f32(ConstView src);
+Buffer linear_f32_to_srgb(ConstView src, Dtype dst);
+
+}  // namespace focal

focalpy-0.0.1/include/focal/io.hpp

@@ -0,0 +1,31 @@
+#pragma once
+
+#include <string>
+
+#include "focal/buffer.hpp"
+#include "focal/view.hpp"
+
+namespace focal {
+
+// Image file I/O, backed by stb_image / stb_image_write (vendored in
+// third_party/).  Supports 8-bit PNG, JPEG, BMP, TGA and reads GIF/PSD/PIC.
+// Not for 16-bit PNG, EXR, TIFF or camera raw -- swap in libpng /
+// libjpeg-turbo / tinyexr / libraw when those matter.
+//
+// Files hold sRGB-encoded bytes.  load() decodes them to LINEAR f32 so that
+// everything downstream -- blurring, resizing, compositing -- is correct;
+// save() encodes back.  Use load_raw()/save_raw() only when you deliberately
+// want the stored values, e.g. inspecting a file's actual bytes.
+
+// Decode to linear f32, channels as stored in the file (1, 2, 3 or 4).
+// Pass want_channels to force a channel count (1 = grey, 3 = RGB, 4 = RGBA).
+Buffer load(const std::string &path, int want_channels = 0);
+
+// Decode to u8 exactly as stored, with no transfer-function conversion.
+Buffer load_raw(const std::string &path, int want_channels = 0);
+
+// Encode linear f32 (or pass u8 through) and write.  Format comes from the
+// file extension: .png .jpg .jpeg .bmp .tga
+void save(const std::string &path, ConstView img, int jpeg_quality = 95);
+
+}  // namespace focal

focalpy-0.0.1/include/focal/ops/blur.hpp

@@ -0,0 +1,20 @@
+#pragma once
+
+#include <vector>
+
+#include "focal/border.hpp"
+#include "focal/view.hpp"
+
+namespace focal {
+
+// Normalized 1D Gaussian weights, radius = int(truncate * sigma + 0.5).
+// Matches scipy.ndimage's kernel exactly, which is what the tests compare to.
+std::vector<float> gaussian_kernel1d(float sigma, float truncate = 4.0f);
+
+// Separable Gaussian blur.  src and dst must be F32, same shape, and must not
+// alias.  Separable means two 1D passes (O(2r) per pixel) instead of one 2D
+// convolution (O(r^2)) -- the whole reason to special-case Gaussians.
+void gaussian_blur(ConstView src, View dst, float sigma,
+                   Border border = Border::Reflect101, float cval = 0.0f);
+
+}  // namespace focal

focalpy-0.0.1/include/focal/ops/point.hpp

@@ -0,0 +1,110 @@
+#pragma once
+
+#include <cstdint>
+
+#include "focal/check.hpp"
+#include "focal/view.hpp"
+
+namespace focal {
+
+// Point operations: every output sample depends only on the sample at the same
+// position.  No neighbourhood, no border handling, and safe to run in place
+// (pass the same memory as src and dst).
+//
+// WHICH COLOUR SPACE
+//
+// Filtering must happen in linear light because blurring MIXES pixels, and
+// mixing light is physics.  Tone adjustment is different -- it remaps a single
+// value, and the result people expect comes from remapping DISPLAY-REFERRED
+// (sRGB-encoded) values.  So:
+//
+//   exposure()             linear.  It is a light-amount change: multiply.
+//   gamma()                display.  Definitionally an encoding change.
+//   brightness_contrast()  display.  Matches what an editor's sliders do.
+//   apply_lut()            display, normally -- it is a curve on tone.
+//   invert(), blend()      either; blend of colours wants linear.
+//
+// These functions do not convert for you.  Hand them a view already in the
+// space you mean.
+
+// The workhorse.  Everything else in this header is three lines on top of it.
+// fn is called per sample; alpha is passed through untouched when skip_alpha.
+template <typename F>
+void map(ConstView src, View dst, F fn, bool skip_alpha = true) {
+  check_f32(src, "map");
+  check_f32(dst, "map");
+  check_same_shape(src, dst, "map");
+
+  for (int64_t y = 0; y < src.height; ++y) {
+    for (int64_t x = 0; x < src.width; ++x) {
+      for (int64_t c = 0; c < src.channels; ++c) {
+        const float v = src.at<float>(y, x, c);
+        dst.at<float>(y, x, c) =
+            (skip_alpha && is_alpha_channel(src.channels, c)) ? v : fn(v);
+      }
+    }
+  }
+}
+
+
+template <typename F>
+void map2(ConstView src1, ConstView src2, View dst, F fn, bool skip_alpha = true) {
+  check_f32(src1, "map2");
+  check_f32(src2, "map2");
+  check_f32(dst, "map2");
+  check_same_shape(src1, src2, "map2");
+  check_same_shape(src1, dst, "map2");
+
+  for (int64_t y = 0; y < src1.height; ++y) {
+    for (int64_t x = 0; x < src1.width; ++x) {
+      for (int64_t c = 0; c < src1.channels; ++c) {
+        const float v = src1.at<float>(y, x, c);
+        const float w = src2.at<float>(y, x, c);
+        dst.at<float>(y, x, c) =
+            (skip_alpha && is_alpha_channel(src1.channels, c)) ? v : fn(v, w);
+      }
+    }
+  }
+}
+
+// v -> v^g.  Values below zero are left alone (pow of a negative is NaN).
+void gamma(ConstView src, View dst, float g);
+
+// v -> v * 2^stops.  Linear-light only; on encoded values it is meaningless.
+void exposure(ConstView src, View dst, float stops);
+
+// v -> (v - pivot) * contrast + pivot + brightness
+//
+// The pivot is why contrast does not also brighten: it is the value held
+// fixed while everything else spreads away from it.  0.5 for display-referred
+// values, 0.18 (middle grey) if you insist on working linear.
+void brightness_contrast(ConstView src, View dst, float brightness,
+                         float contrast, float pivot = 0.5f);
+
+// v -> 1 - v.
+void invert(ConstView src, View dst);
+
+// v -> clip(v, lo, hi).
+void clip(ConstView src, View dst, float lo = 0.0f, float hi = 1.0f);
+
+// dst = a + (b - a) * t, elementwise.  a and b must have the same shape.
+void blend(ConstView a, ConstView b, View dst, float t);
+
+// Apply a tone curve held as a lookup table.
+//
+// DOMAIN: the n entries span [0, 1] inclusive, so lut[0] is the output for
+// input 0.0 and lut[n-1] the output for 1.0.  Inputs between entries are
+// linearly interpolated; inputs outside [0, 1] are clamped to the ends.
+//
+// This is also the fast path for any expensive curve -- bake gamma or an sRGB
+// transfer into 1024 entries once instead of calling pow() per pixel.
+void apply_lut(ConstView src, View dst, const float *lut, int n);
+
+// Fill `lut` (n entries, same domain as above) by sampling fn over [0, 1].
+template <typename F>
+void bake_lut(float *lut, int n, F fn) {
+  for (int i = 0; i < n; ++i)
+    lut[i] = fn(static_cast<float>(i) / static_cast<float>(n - 1));
+}
+
+}  // namespace focal