API Reference¶

`feneck` ¶

`BiFPN` ¶

Bases: BaseNeck

Bidirectional Feature Pyramid Network for efficient multi-scale feature fusion.

BiFPN introduces weighted bidirectional cross-scale connections for improved feature fusion compared to traditional FPN and PANet. Key innovations include fast normalized fusion, same-level skip connections, and depthwise separable convolutions.

Reference

EfficientDet: Scalable and Efficient Object Detection Tan et al., CVPR 2020 Paper

Parameters:

Name	Type	Description	Default
`in_channels`	`list[int]`	Number of input channels for each feature level	required
`in_strides`	`list[int]`	Stride values for each input feature level	required
`out_channels`	`int`	Number of output channels (same for all levels)	`256`
`num_levels`	`int`	Total number of pyramid levels	`5`
`num_layers`	`int`	Number of BiFPN blocks to stack	`3`
`norm_type`	`Literal['batch', 'group'] \| None`	Normalization type applied to all convolution layers	`None`
`use_fast_attention`	`bool`	Whether to use fast attention for feature fusion	`True`
`epsilon`	`float`	Small value for numerical stability in attention normalization	`0.0001`

`CARAFE` ¶

Bases: BaseNeck

CARAFE Feature Pyramid Network neck module.

Replaces standard FPN upsampling with Content-Aware ReAssembly of FEatures (CARAFE) for improved feature upsampling and multi-scale feature fusion.

This implementation uses standard PyTorch operations without CUDA dependencies.

Reference

CARAFE: Content-Aware ReAssembly of FEatures Wang et al., ICCV 2019 Paper

Parameters:

Name	Type	Description	Default
`in_channels`	`list[int]`	Number of input channels for each feature level	required
`in_strides`	`list[int]`	Stride values for each input feature level (must be increasing)	required
`out_channels`	`int`	Number of output channels (same for all levels)	`256`
`num_levels`	`int \| None`	Total number of output pyramid levels. If None, uses len(in_channels). Must be >= len(in_channels)	`None`
`has_extra_convs`	`bool`	Whether to add extra conv layers for additional pyramid levels. False uses max pooling for one extra level (Faster R-CNN style). True uses strided convolutions for extra levels (RetinaNet/FCOS style)	`False`
`use_c5`	`bool`	Whether to use backbone's highest feature (c5) as input for first extra level. False uses FPN's highest feature (p5) instead. Only affects extra convolutions	`True`
`carafe_scale_factor`	`int`	Scale factor for CARAFE upsampling	`2`
`carafe_up_kernel`	`int`	Kernel size for CARAFE reassembly operation	`5`
`carafe_encoder_kernel`	`int`	Kernel size for CARAFE content encoder	`3`
`carafe_encoder_dilation`	`int`	Dilation for CARAFE content encoder	`1`
`carafe_compressed_channels`	`int`	Intermediate channels in CARAFE	`64`
`norm_type`	`Literal['batch', 'group'] \| None`	Normalization type applied to all convolution layers	`None`
`relu_before_extra_convs`	`bool`	Whether to apply ReLU activation before extra convolutions	`True`

`CustomCSPPAN` ¶

Bases: BaseNeck

Custom CSP-PAN neck with transformer enhancement.

Adapted from PaddleDetection CustomCSPPAN implementation.

Reference

PP-YOLOv2: A Practical Object Detector Huang et al., 2021 Paper

Parameters:

Name	Type	Description	Default
`in_channels`	`list[int]`	Number of input channels for each feature level	required
`in_strides`	`list[int]`	Stride values for each input feature level	required
`out_channels`	`int`	Number of output channels (same for all levels)	`256`
`norm_type`	`Literal['batch', 'group'] \| None`	Normalization type applied to all convolution layers	`None`
`activation`	`str`	Activation function type	`'relu'`
`stage_num`	`int`	Number of stages in each CSP block	`1`
`block_num`	`int`	Number of basic blocks in each CSP stage	`3`
`spp`	`bool`	Whether to use SPP (Spatial Pyramid Pooling) in the deepest level	`False`
`use_alpha`	`bool`	Whether to use learnable alpha parameter in residual connections	`False`
`width_mult`	`float`	Width multiplier for channel scaling	`1.0`
`depth_mult`	`float`	Depth multiplier for block number scaling	`1.0`
`use_transformer`	`bool`	Whether to use transformer enhancement on deepest feature	`False`
`transformer_num_heads`	`int`	Number of attention heads in transformer	`4`
`transformer_num_layers`	`int`	Number of transformer encoder layers	`4`
`transformer_dim_feedforward`	`int`	Feedforward dimension in transformer	`2048`
`transformer_dropout`	`float`	Dropout rate in transformer	`0.1`

`DyHead` ¶

Bases: BaseNeck

Dynamic Head neck with attention mechanisms for object detection.

Adapted from Microsoft's DynamicHead implementation with three types of attention: - Scale-aware attention: Combines features from different pyramid levels - Spatial-aware attention: Uses deformable convolutions for spatial modeling - Task-aware attention: Uses dynamic ReLU for channel-wise adaptive activation

DyHead is typically used after an FPN neck, which is why all input levels are required to have the same number of channels (standard FPN output).

Reference

Dynamic Head: Unifying Object Detection Heads with Attentions Dai et al., CVPR 2021 Paper

Parameters:

Name	Type	Description	Default
`in_channels`	`list[int]`	Number of input channels for each feature level (must be same for all levels)	required
`in_strides`	`list[int]`	Stride values for each input feature level	required
`out_channels`	`int`	Number of output channels (same for all levels)	`256`
`num_blocks`	`int`	Number of DyHead blocks to stack	`6`
`norm_type`	`Literal['batch', 'group'] \| None`	Normalization type applied to convolutions	`'group'`

`FPN` ¶

Bases: BaseNeck

Feature Pyramid Network neck module.

Reference

Feature Pyramid Networks for Object Detection Lin et al., CVPR 2017 Paper

Parameters:

Name	Type	Description	Default
`in_channels`	`list[int]`	Number of input channels for each feature level	required
`in_strides`	`list[int]`	Stride values for each input feature level (must be increasing)	required
`out_channels`	`int`	Number of output channels (same for all levels)	`256`
`num_levels`	`int \| None`	Total number of output pyramid levels. If None, uses len(in_channels). Must be >= len(in_channels)	`None`
`has_extra_convs`	`bool`	Whether to add extra conv layers for additional pyramid levels. False uses max pooling for one extra level (Faster R-CNN style). True uses strided convolutions for extra levels (RetinaNet/FCOS style)	`False`
`use_c5`	`bool`	Whether to use backbone's highest feature (c5) as input for first extra level. False uses FPN's highest feature (p5) instead. Only affects extra convolutions	`True`
`norm_type`	`Literal['batch', 'group'] \| None`	Normalization type applied to all convolution layers	`None`
`relu_before_extra_convs`	`bool`	Whether to apply ReLU activation before extra convolutions	`True`

`FeaturePyramidExtender` ¶

Bases: BaseNeck

Extends and transforms feature pyramids by adding levels and optionally projecting channels.

This neck can:

Add extra feature levels at higher or lower resolutions
Optionally project all features to uniform channel count
Or do both simultaneously

Useful for preprocessing before other necks that need specific level counts or channel uniformity, or for extending necks like CustomCSPPAN that can't create additional levels themselves.

Parameters:

Name	Type	Description	Default
`in_channels`	`list[int]`	Number of input channels for each feature level	required
`in_strides`	`list[int]`	Stride values for each input feature level (must be increasing)	required
`out_channels`	`int`	Number of output channels (same for all levels). If None, keeps original channels	`256`
`num_levels`	`int \| None`	Total number of output levels. If None, uses len(in_channels)	`None`
`add_higher_res`	`bool`	Whether to add higher resolution levels (lower strides) at the beginning. If False, only adds lower resolution levels (higher strides) at the end	`False`
`project_channels`	`bool`	Whether to project input features to out_channels. If False, only extra levels use out_channels while original features keep their channels	`True`
`norm_type`	`Literal['batch', 'group'] \| None`	Normalization type applied to convolution layers	`None`
`relu_before_downsample`	`bool`	Whether to apply ReLU before downsampling convolutions	`True`

Usage Examples

>>> # Just add levels, keep original channels
>>> extender = FeaturePyramidExtender(
...     in_channels=[256, 512, 1024],
...     in_strides=[8, 16, 32],
...     out_channels=256,  # Only for new levels
...     num_levels=5,
...     project_channels=False
... )
>>> # Output channels: [256, 512, 1024, 256, 256]

>>> # Add levels + unify channels
>>> extender = FeaturePyramidExtender(
...     in_channels=[256, 512, 1024],
...     in_strides=[8, 16, 32],
...     out_channels=256,
...     num_levels=5,
...     project_channels=True  # Project all to 256 channels
... )
>>> # Output channels: [256, 256, 256, 256, 256]

>>> # Just unify channels without adding levels
>>> extender = FeaturePyramidExtender(
...     in_channels=[256, 512, 1024],
...     in_strides=[8, 16, 32],
...     out_channels=256,
...     project_channels=True
... )
>>> # Output channels: [256, 256, 256]

>>> # Add higher resolution levels
>>> extender = FeaturePyramidExtender(
...     in_channels=[512, 1024],
...     in_strides=[16, 32],
...     out_channels=256,
...     num_levels=4,  # Add P2 (stride 4) and P3 (stride 8)
...     add_higher_res=True
... )
>>> # Output strides: [4, 8, 16, 32]

`out_channels` `property` ¶

Output channels for each feature level.

`out_strides` `property` ¶

Output strides for each feature level.

`HRFPN` ¶

Bases: BaseNeck

High-Resolution Feature Pyramid Network neck module.

HRFPN aggregates multi-resolution feature representations by upsampling all feature levels to the highest resolution, concatenating them, then generating pyramid levels through pooling. Originally designed for HRNet but works with any multi-scale backbone.

Reference

Deep High-Resolution Representation Learning for Visual Recognition Wang et al., TPAMI 2021 Paper

Parameters:

Name	Type	Description	Default
`in_channels`	`list[int]`	Number of input channels for each feature level	required
`in_strides`	`list[int]`	Stride values for each input feature level (must be increasing)	required
`out_channels`	`int`	Number of output channels (same for all pyramid levels)	`256`
`num_levels`	`int`	Number of output pyramid levels to generate	`5`
`pooling_type`	`Literal['max', 'avg']`	Pooling operation for generating lower resolution levels ('max' or 'avg')	`'avg'`
`norm_type`	`Literal['batch', 'group'] \| None`	Normalization type applied to convolution layers	`None`
`stride`	`int`	Stride for the final 3x3 convolutions in each pyramid level	`1`

`out_strides` `property` ¶

Output strides for each pyramid level.

`LRFPN` ¶

Bases: BaseNeck

Location-Refined Feature Pyramid Network (LR-FPN).

The first input feature is always used as F1 (shallow). All subsequent inputs are treated as higher-level features F2, F3, ..., each refined by SPIEM and CIM. The last CIM output serves as the base of the pyramid. Additional pyramid levels are built top-down (if multiple higher features are available) and with stride-2 convolutions until num_levels outputs are produced.

Reference

LR-FPN: Enhancing Remote Sensing Object Detection with Location Refined Feature Pyramid Network Li et al., 2024 Paper

Parameters:

Name	Type	Description	Default
`in_channels`	`list[int]`	Number of input channels for each feature level	required
`in_strides`	`list[int]`	Stride values for each input feature level (must be increasing)	required
`out_channels`	`int`	Number of output channels (same for all levels)	`256`
`num_levels`	`int \| None`	Total number of output pyramid levels (>= 1). Defaults to len(in_channels) - 1 + 2 (paper's setting).	`None`
`norm_type`	`Literal['batch', 'group'] \| None`	Normalization type applied to ConvNormLayer	`None`

`NASFPN` ¶

Bases: BaseNeck

Neural Architecture Search Feature Pyramid Network.

NAS-FPN uses learned feature fusion patterns discovered through neural architecture search. It employs dynamic feature recycling and channel attention for efficient multi-scale feature fusion. Generates 5 pyramid levels (P3-P7) regardless of input configuration.

Reference

NAS-FPN: Learning Scalable Feature Pyramid Architecture for Object Detection Ghiasi et al., CVPR 2019 Paper

Parameters:

Name	Type	Description	Default
`in_channels`	`list[int]`	Number of input channels for each feature level	required
`in_strides`	`list[int]`	Stride values for each input feature level	required
`out_channels`	`int`	Number of output channels (same for all levels)	`256`
`num_repeats`	`int`	Number of NAS-FPN cells to stack	`5`
`norm_type`	`str \| None`	Normalization type applied to convolution layers	`'batch'`

`PAFPN` ¶

Bases: BaseNeck

Path Aggregation Feature Pyramid Network neck module.

PAFPN enhances FPN by adding a bottom-up path augmentation that shortens the information path between lower and top feature levels. This preserves fine-grained localization information through direct connections after the initial FPN processing.

Reference

Path Aggregation Network for Instance Segmentation Liu et al., CVPR 2018 Paper

Parameters:

Name	Type	Description	Default
`in_channels`	`list[int]`	Number of input channels for each feature level	required
`in_strides`	`list[int]`	Stride values for each input feature level (must be increasing)	required
`out_channels`	`int`	Number of output channels (same for all levels)	`256`
`num_levels`	`int \| None`	Total number of output pyramid levels. If None, uses len(in_channels). Must be >= len(in_channels)	`None`
`has_extra_convs`	`bool`	Whether to add extra conv layers for additional pyramid levels. False uses max pooling for one extra level (Faster R-CNN style). True uses strided convolutions for extra levels (RetinaNet/FCOS style)	`False`
`use_c5`	`bool`	Whether to use backbone's highest feature (c5) as input for first extra level. False uses FPN's highest feature (p5) instead. Only affects extra convolutions	`True`
`norm_type`	`Literal['batch', 'group'] \| None`	Normalization type applied to all convolution layers	`None`
`relu_before_extra_convs`	`bool`	Whether to apply ReLU activation before extra convolutions	`True`

`SimpleFPN` ¶

Bases: BaseNeck

Simple Feature Pyramid Network for transformer-based backbones.

SimpleFPN is designed for non-hierarchical backbones (like Vision Transformers) that output single-scale features. It creates a feature pyramid by applying convolutions at different strides to generate multi-scale representations.

Reference

Exploring Plain Vision Transformer Backbones for Object Detection Li et al., ECCV 2022 Paper

Parameters:

Name	Type	Description	Default
`in_channels`	`int \| list[int]`	Number of input channels (int or single-element list)	required
`in_strides`	`int \| list[int]`	Input stride (int or single-element list)	required
`out_channels`	`int`	Number of output channels (same for all pyramid levels)	`256`
`num_levels`	`int`	Number of pyramid levels to generate	`5`
`start_level`	`int`	Index of pyramid level that matches input resolution. Levels below this index will have higher resolution (upsampled), levels above will have lower resolution (downsampled)	`2`
`norm_type`	`Literal['batch', 'group'] \| None`	Normalization type applied to all convolution layers	`None`

Usage Examples

>>> # ViT outputs 14x14 features at stride 16
>>> # We want 5 levels: stride 4, 8, 16, 32, 64
>>> # Input stride 16 matches level 2, so start_level=2
>>> neck = SimpleFPN(
...     in_channels=768, in_strides=16, out_channels=256,
...     num_levels=5, start_level=2
... )
>>> # Output: [stride4, stride8, stride16, stride32, stride64]
>>> #         [level0,  level1, level2,   level3,   level4]
>>> #         [upsample, upsample, same, downsample, downsample]

API Reference¶

feneck ¶

BiFPN ¶

CARAFE ¶

CustomCSPPAN ¶

DyHead ¶

FPN ¶

FeaturePyramidExtender ¶

out_channels property ¶

out_strides property ¶

HRFPN ¶

out_strides property ¶

LRFPN ¶

NASFPN ¶

PAFPN ¶

SimpleFPN ¶

`feneck` ¶

`BiFPN` ¶

`CARAFE` ¶

`CustomCSPPAN` ¶

`DyHead` ¶

`FPN` ¶

`FeaturePyramidExtender` ¶

`out_channels` `property` ¶

`out_strides` `property` ¶

`HRFPN` ¶

`out_strides` `property` ¶

`LRFPN` ¶

`NASFPN` ¶

`PAFPN` ¶

`SimpleFPN` ¶