backend.solve ============= .. py:module:: backend.solve Attributes ---------- .. autoapisummary:: backend.solve.logger backend.solve.PIN_ATTR Functions --------- .. autoapisummary:: backend.solve.solve backend.solve._build_candidate_graph backend.solve._solve_full backend.solve._solve_window backend.solve._slice_input_for_single_window backend.solve._solve_single_window backend.solve._solve_chunked backend.solve._set_pinning_on_graph backend.solve._add_to_combined_solution backend.solve.construct_solver Module Contents --------------- .. py:data:: logger .. py:data:: PIN_ATTR :value: 'pinned' .. py:function:: solve(solver_params: backend.solver_params.SolverParams, input_data: numpy.ndarray, on_solver_update: collections.abc.Callable | None = None, scale: list | None = None) -> networkx.DiGraph Get a tracking solution for the given segmentation and parameters. Constructs a candidate graph from the segmentation, a solver from the parameters, and then runs solving and returns a networkx graph with the solution. Most of this functionality is implemented in the motile toolbox. Args: solver_params (SolverParams): The solver parameters to use when initializing the solver input_data (np.ndarray): The input segmentation or points list to run tracking on. If 2D, assumed to be a list of points, otherwise a segmentation. on_solver_update (Callable, optional): A function that is called whenever the motile solver emits an event. The function should take a dictionary of event data, and can be used to track progress of the solver. Defaults to None. scale (list, optional): The scale of the data in each dimension. Returns: nx.DiGraph: A solution graph where the ids of the nodes correspond to the time and ids of the passed in segmentation labels. See the motile_toolbox for exact implementation details. .. py:function:: _build_candidate_graph(input_data: numpy.ndarray, solver_params: backend.solver_params.SolverParams, scale: list | None = None) -> networkx.DiGraph Build the candidate graph from input data. .. py:function:: _solve_full(cand_graph: networkx.DiGraph, solver_params: backend.solver_params.SolverParams, on_solver_update: collections.abc.Callable | None = None) -> networkx.DiGraph Solve the tracking problem on the full candidate graph at once. .. py:function:: _solve_window(window_subgraph: networkx.DiGraph, solver_params: backend.solver_params.SolverParams, on_solver_update: collections.abc.Callable | None = None) -> networkx.DiGraph | None Solve a single window subgraph. This is the core solving logic shared by both single window mode and chunked solving. Args: window_subgraph: The subgraph for this window. If any nodes or edges have the PIN_ATTR attribute set, a Pin constraint will be used. solver_params: The solver parameters. on_solver_update: Callback for solver progress updates. Returns: The solution graph for this window, or None if the window has no nodes. .. py:function:: _slice_input_for_single_window(input_data: numpy.ndarray, window_size: int, window_start: int) -> tuple[numpy.ndarray, int] Slice input data to only include frames needed for single window solving. This avoids building the full candidate graph when only solving a single window. Args: input_data: The full input segmentation or points list. window_size: Number of frames in the window. window_start: Starting frame index for the window. Returns: A tuple of (sliced_data, time_offset) where time_offset is the actual start frame used (may differ from window_start if it was out of bounds). Raises: ValueError: If window_start is beyond the data range. .. py:function:: _solve_single_window(input_data: numpy.ndarray, solver_params: backend.solver_params.SolverParams, on_solver_update: collections.abc.Callable | None = None, scale: list | None = None) -> networkx.DiGraph Solve a single window for interactive parameter testing. Slices the input data to only include frames in the window, builds a candidate graph from that slice, solves, and restores original time values. Args: input_data: The full input segmentation or points list. solver_params: The solver parameters including window_size and single_window_start. on_solver_update: Callback for solver progress updates. scale: The scale of the data in each dimension. Returns: The solution graph with original time values. .. py:function:: _solve_chunked(cand_graph: networkx.DiGraph, solver_params: backend.solver_params.SolverParams, on_solver_update: collections.abc.Callable | None = None) -> networkx.DiGraph Solve the tracking problem in chunks using a sliding window approach. This function solves the tracking problem in windows of `window_size` frames, with `overlap_size` frames of overlap between consecutive windows. The overlap region from the previous window is pinned (fixed) when solving the next window to maintain consistency across windows. Args: cand_graph: The full candidate graph with all nodes and edges. solver_params: The solver parameters including window_size and overlap_size. on_solver_update: Callback for solver progress updates. Returns: The combined solution graph from all windows. .. py:function:: _set_pinning_on_graph(cand_graph: networkx.DiGraph, solution_graph: networkx.DiGraph, overlap_start: int, overlap_end: int) -> None Set PIN_ATTR on candidate graph nodes/edges in the overlap region. For all nodes and edges in the overlap region [overlap_start, overlap_end), sets PIN_ATTR to True if selected in the solution, False if not selected. Args: cand_graph: The full candidate graph to modify in place. solution_graph: The solution graph from the current window. overlap_start: Start frame of overlap region (inclusive). overlap_end: End frame of overlap region (exclusive). .. py:function:: _add_to_combined_solution(combined: networkx.DiGraph, window_solution: networkx.DiGraph, from_frame: int | None = None) -> None Add nodes and edges from window solution to the combined solution. Args: combined: The combined solution graph to add to. window_solution: The window solution to add from. from_frame: If specified, only add nodes at or after this frame. .. py:function:: construct_solver(cand_graph: networkx.DiGraph, solver_params: backend.solver_params.SolverParams) -> motile.Solver Construct a motile solver with the parameters specified in the solver params object. Args: cand_graph (nx.DiGraph): The candidate graph to use in the solver solver_params (SolverParams): The costs and constraints to use in the solver Returns: Solver: A motile solver with the specified graph, costs, and constraints.