Dependencies for dpt_head.py in Robbyant/lingbot-map: Complete Dependency Guide

The dpt_head.py module in Robbyant/lingbot-map depends only on Python's standard library, the PyTorch framework, and two internal utility modules from the same package, keeping all neural network blocks self-contained within the file.

The dpt_head.py file in the Robbyant/lingbot-map repository implements the DPT (Dense Prediction Transformer) head architecture for dense prediction tasks. Understanding the dependencies for dpt_head.py is essential for integration, as this module maintains a minimal external footprint while housing most of its architecture definitions locally.

Standard Library Dependencies

The file imports a limited set of standard library modules, primarily for type hinting and system-level operations.

typing Module

dpt_head.py imports specific type hints from the typing module to ensure API clarity:

• List
• Dict
• Tuple
• Union

These annotations appear throughout the class definitions and function signatures in lingbot_map/heads/dpt_head.py to specify tensor shapes and configuration types.

os Module

The os module is imported at the top of the file (around line 11) but serves as a common placeholder and is not directly utilized in the core implementation logic shown in the source.

PyTorch Framework Dependencies

As a deep learning module, dpt_head.py relies entirely on the PyTorch ecosystem for tensor operations and neural network layers.

torch and torch.nn

The module imports the core torch package and torch.nn (typically aliased as nn) to define:

• Tensor operations: Core tensor manipulations and device management
• Neural network layers: nn.Conv2d, nn.LayerNorm, and other layer types used in the DPTHead class
• Module base class: nn.Module serves as the parent class for the head implementation

torch.nn.functional

The functional API (torch.nn.functional, often imported as F) provides stateless operations used within the forward pass, specifically F.interpolate for upsampling feature maps to target resolutions.

Internal Package Dependencies

Beyond PyTorch and standard library types, dpt_head.py imports three specific utilities from sibling modules within the lingbot_map.heads package (lines 11-18 of the file).

head_act.py Utilities

activate_head: Imported from lingbot_map.heads.head_act, this function handles the final activation of predictions and confidence maps, applying the configured activation functions (such as "inv_log" or "expp1") to the raw network outputs.

utils.py Positional Embedding Functions

Two critical utilities come from lingbot_map.heads.utils:

• create_uv_grid: Generates a UV positional-embedding grid used for spatial encoding
• position_grid_to_embed: Converts the UV grid into an embedding tensor suitable for injection into the transformer features

These utilities enable the pos_embed=True configuration option that adds positional information to the fused features.

Self-Contained Architecture Components

Unlike many deep learning modules that import utility blocks from external files, dpt_head.py defines its core architecture components within the same file. These internal classes do not introduce additional dependencies:

• FeatureFusionBlock: Handles multi-scale feature fusion between transformer layers
• ResidualConvUnit: Provides residual convolutional processing for feature refinement
• _make_fusion_block: Factory function for creating fusion block instances

Because these components are defined locally (lines following the imports), the module avoids circular dependencies and remains portable within the repository.

Complete Import Structure

According to the source code at lines 11-18 of lingbot_map/heads/dpt_head.py, the import structure is:

import os
from typing import List, Dict, Tuple, Union

import torch
import torch.nn as nn
import torch.nn.functional as F

from lingbot_map.heads.head_act import activate_head
from lingbot_map.heads.utils import create_uv_grid, position_grid_to_embed

The external dependency on torch is formally declared in the repository's pyproject.toml file, which specifies version constraints for the PyTorch framework.

Installation and Usage Example

To use dpt_head.py, ensure PyTorch is installed and the lingbot_map package is available in your Python path. The following example demonstrates instantiation with the minimal dependency set:

import torch
from lingbot_map.heads.dpt_head import DPTHead

# Configuration

dim_in = 768
patch_size = 14
output_dim = 4

# Initialize head

dpt_head = DPTHead(
    dim_in=dim_in,
    patch_size=patch_size,
    output_dim=output_dim,
    activation="inv_log",
    conf_activation="expp1",
    features=256,
    out_channels=[256, 512, 1024, 1024],
    intermediate_layer_idx=[0, 1, 2, 3],
    pos_embed=True,
    feature_only=False,
    down_ratio=1,
)

# Dummy inputs simulating transformer outputs

B, S, C, H, W = 2, 5, dim_in, 224, 224
tokens = [torch.randn(B, S, dim_in) for _ in range(4)]
images = torch.rand(B, S, 3, H, W)

# Forward pass

preds, conf = dpt_head(tokens, images, patch_start_idx=0)
print(preds.shape, conf.shape)  # torch.Size([2, 5, 1, 224, 224])

Feature-Only Mode

When using feature_only=True, the module returns fused feature maps without applying the activation head:

dpt_head_feat = DPTHead(
    dim_in=dim_in,
    feature_only=True,
    # ... other parameters

)

features = dpt_head_feat(tokens, images, patch_start_idx=0)

Summary

• Minimal external footprint: dpt_head.py requires only PyTorch and Python standard library types (typing, os).
• Internal utilities: Depends on activate_head from head_act.py and create_uv_grid/position_grid_to_embed from utils.py.
• Self-contained blocks: Core neural network components (FeatureFusionBlock, ResidualConvUnit) are defined within the file, requiring no external imports.
• Import location: All dependencies are declared in lines 11-18 of lingbot_map/heads/dpt_head.py.
• Formal declaration: PyTorch dependency is specified in pyproject.toml for package management.

Frequently Asked Questions

Does dpt_head.py require any external libraries beyond PyTorch?

No. According to the source code in lingbot_map/heads/dpt_head.py, the module only requires PyTorch and Python's standard library. All neural network layer definitions are self-contained within the file, and the only non-standard imports are from sibling modules (head_act.py and utils.py) within the same lingbot_map package.

What are the internal helper functions imported by dpt_head.py?

The file imports three internal utilities: activate_head from lingbot_map.heads.head_act for final output activation, and create_uv_grid along with position_grid_to_embed from lingbot_map.heads.utils for generating positional embeddings. These functions are essential for the confidence mapping and spatial encoding features.

Are the neural network blocks in dpt_head.py imported from other files?

No. While many repositories split architecture components across multiple files, dpt_head.py defines FeatureFusionBlock, ResidualConvUnit, and _make_fusion_block locally within the same file. This design choice eliminates additional import dependencies and keeps the module self-contained.

Where are the dependencies declared in the repository?

The PyTorch dependency is formally declared in pyproject.toml at the repository root, which specifies the version constraints for the torch package. The specific import statements for dpt_head.py are located at lines 11-18 of lingbot_map/heads/dpt_head.py, where you can verify the exact module paths for both external and internal dependencies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}