Some doc updates and cosmetics

Author: constantinpape

.github/workflows/docs.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Install package and docs tooling
         run: python -m pip install -v ".[test]" pdoc
       - name: Build docs
-        run: pdoc bioimage_cpp -o docs
+        run: PYTHONPATH=src pdoc bioimage_cpp -o docs
       - uses: actions/upload-pages-artifact@v3
         with:
           path: docs

AGENTS.md

@@ -192,10 +192,10 @@ Don't add `std::chrono` snippets ad hoc; use the existing macros so future profi
 
 ## Documentation
 
-`README.md` covers: what `bioimage-cpp` is and isn't, install/build, minimal examples, design philosophy. Public functions need concise docstrings documenting input shapes, supported dtypes, output shapes/dtypes, copy behavior, background-label behavior (if relevant), and axis/coordinate conventions.
-
 Update `MIGRATION_GUIDE.md` whenever public functionality changes, so users migrating from `nifty`/`affogato` see the corresponding `bioimage-cpp` API, behavioral differences, and intentional improvements.
 
+The documentation is build via pdoc, see `.github/workflow/docs.yaml`.
+
 ## Checklist when modifying code
 
 1. Reuse existing `detail/` helpers; add new shared ones rather than duplicating.

README.md

@@ -1,73 +1,5 @@
 # bioimage-cpp
 
-Stand-alone implementation of image analysis and segmentaton functionality in C++ with minimal python bindings.
+Image processing and segmentation functionality in C++ with light-weight python bindings through nanobind and minimal dependencies to enable distribution via pip.
 
-`bioimage-cpp` is a small C++/Python package for dependency-light bioimage-analysis algorithms that are difficult to install from larger C++ libraries. It exposes NumPy-based Python APIs backed by a focused C++20 core.
-
-## Install
-
-```bash
-python -m pip install bioimage-cpp
-```
-
-## Build from source
-
-```bash
-python -m pip install -v ".[test]"
-pytest -q
-```
-
-## Example
-
-```python
-import numpy as np
-import bioimage_cpp as bic
-
-labels = np.array([1, 3, 2, 1], dtype=np.uint64)
-relabeling = {1: 10, 2: 20, 3: 30}
-
-out = bic.utils.take_dict(relabeling, labels)
-# array([10, 30, 20, 10], dtype=uint64)
-```
-
-```python
-affinities = np.ones((2, 4, 4), dtype=np.float32)
-offsets = [[0, 1], [1, 0]]
-
-segmentation = bic.segmentation.mutex_watershed(
-    affinities,
-    offsets,
-    number_of_attractive_channels=2,
-)
-```
-
-```python
-image = np.arange(64, dtype=np.float32).reshape(8, 8)
-matrix = np.array([[1.0, 0.0, 0.5], [0.0, 1.0, -1.0]])
-
-transformed = bic.transformation.affine_transform(
-    image,
-    matrix,
-    order=3,
-    fill_value=0,
-)
-```
-
-```python
-graph = bic.graph.UndirectedGraph.from_edges(4, [[0, 1], [1, 2], [2, 3]])
-graph.find_edge(2, 1)
-# 1
-
-grid = bic.graph.grid_graph((64, 64))
-grid.number_of_edges
-# 8064
-
-edge_weights = bic.graph.grid_boundary_features(grid, boundary_map)
-local_weights, valid_edges, lifted_uvs, lifted_weights, offset_ids = (
-    bic.graph.grid_affinity_features_with_lifted(grid, affinities, offsets)
-)
-```
-
-## Scope
-
-The project is not a compatibility layer for `nifty`, `vigra`, or other large libraries. It keeps I/O and heavy dependencies out of the C++ core; callers should use existing Python packages for file formats and pass NumPy arrays into `bioimage-cpp`.
+Please refer to [the documentation](https://computational-cell-analytics.github.io/bioimage-cpp/) for details.

src/bioimage_cpp/__init__.py

@@ -1,8 +1,8 @@
-"""`bioimage_cpp` implements functionality needed for image procesing in C++.
+"""`bioimage_cpp` implements image processing and segmentation functionality in C++.
 It generates light-weight python bindings with nanobind with minimal dependencies to enable distribution via pip.
 
-The main goal of this library is to provide functionality that is missing from scipy or scikit-image or
-to provide more performant versions of functionality from these libraries.
+The main goal of this library is to provide functionality that is missing from scipy or scikit-image,
+or to provide more performant versions of functionality from these libraries.
 
 The functionality implemented here bundles and improves algorithms etc. from:
 - [affogato](https://github.com/constantinpape/affogato)
@@ -19,6 +19,43 @@
 
 TODO: document once on pip / conda
 
+## Functionality
+
+This library provides the following functionality:
+- `affinities`: functionality for deriving affinities from segmentations.
+- `filters`: efficient implementation of convolutional image filters.
+- `graph`: graph creation and graph (partitioning) algorithms.
+- `segmentation`: image segmentation functionality.
+- `transformation`: affine transformations.
+- `util`: misc utility functionality.
+
+## Example
+
+Below is a simple example for creating and partitioning a graph with this library.
+For more realistic use-cases check out [the migration guide](migration-guide).
+
+```python
+import numpy as np
+import bioimage_cpp as bic
+
+# Create a graph with 50 nodes.
+graph = bic.graph.undirected_graph(number_of_nodes=50)
+
+# Insert a bunch of edges forming a chain.
+graph.insert_edges(
+    np.concatenate([np.arange(0, 49)[:, None], np.arange(1, 50)[:, None]], axis=1)
+)
+
+# Create edge weights in [-1, 1].
+weights = 2 * np.random.rand(graph.number_of_edges) - 1
+
+# Partition the graph via multicut (greedy solver).
+objective = bic.graph.MulticutObjective(graph, weights)
+solver = bic.graph.GreedyAdditiveMulticut()
+partition = solver.optimize(objective)
+print("Partitioned into", len(np.unique(partition)), "elements")
+```
+
 .. include:: ../../MIGRATION_GUIDE.md
 """