Implementation:Tencent Ncnn ParamDict

Knowledge Sources	Tencent_Ncnn
Domains	Model Loading, Parameter Storage
Last Updated	2026-02-09 19:00 GMT

Overview

Parameter dictionary that stores and retrieves typed layer configuration values by integer ID, supporting text and binary model file parsing.

Description

The ParamDict class is a core data structure used by every layer in ncnn to receive its configuration parameters during model loading. It stores up to NCNN_MAX_PARAM_COUNT (32) parameter slots, each identified by an integer ID and supporting multiple typed values.

The implementation uses the pimpl (pointer to implementation) pattern with a ParamDictPrivate class for ABI stability. Each parameter slot in the private data stores:

• A type tag indicating the value type:
  • 0 = null (unset)
  • 1 = int or float (ambiguous, legacy)
  • 2 = int
  • 3 = float
  • 4 = array of int/float
  • 5 = array of int
  • 6 = array of float
  • 7 = string
• A union of int and float for scalar values
• A Mat for array values (stored as a 1D tensor)
• A std::string for string values

Getter methods are overloaded by return type (int, float, Mat, std::string) and accept a default value that is returned when the parameter slot type is null (unset). This allows layers to provide sensible defaults for optional parameters.

The class provides two parser methods (accessed by the friend class Net):

• load_param() -- Reads key=value pairs from ncnn's text param format. Uses a custom vstr_to_float() function that avoids locale-dependent strtof for portability across different system locales.
• load_param_bin() -- Reads parameters from ncnn's binary param format using type-length-value encoding for compact storage.

Array parameters are stored as negative keys in the text format (e.g., -23303=3,1,1,1 means param ID 3 is an array of 3 elements: 1,1,1). The negative sign signals that the value is an array rather than a scalar.

Usage

Use ParamDict whenever implementing a custom layer that needs to read configuration values from the model file. During load_param(), call pd.get(id, default_value) with the parameter IDs defined in ncnn's layer parameter documentation. ParamDict is also used internally by the Net class during model loading to deserialize layer parameters from .param or .param.bin files.

Code Reference

Source Location

• Repository: Tencent_Ncnn
• Header: src/paramdict.h (66 lines)
• Implementation: src/paramdict.cpp (641 lines)

Signature

#define NCNN_MAX_PARAM_COUNT 32

namespace ncnn {

class NCNN_EXPORT ParamDict
{
public:
    ParamDict();
    virtual ~ParamDict();

    // copy and assign
    ParamDict(const ParamDict&);
    ParamDict& operator=(const ParamDict&);

    // get type (0=null, 1=int/float, 2=int, 3=float, 4-6=array, 7=string)
    int type(int id) const;

    // get int value with default
    int get(int id, int def) const;
    // get float value with default
    float get(int id, float def) const;
    // get array value with default
    Mat get(int id, const Mat& def) const;
    // get string value with default
    std::string get(int id, const std::string& def) const;

    // set int
    void set(int id, int i);
    // set float
    void set(int id, float f);
    // set array
    void set(int id, const Mat& v);
    // set string
    void set(int id, const std::string& s);

protected:
    friend class Net;
    void clear();
    int load_param(const DataReader& dr);
    int load_param_bin(const DataReader& dr);

private:
    ParamDictPrivate* const d;
};

} // namespace ncnn

Import

#include "ncnn/paramdict.h"

I/O Contract

Inputs

Name	Type	Required	Description
id	int	Yes	Parameter slot identifier (0 to 31)
def	int / float / Mat / std::string	Yes (for get)	Default value returned when the parameter is not set
dr	const DataReader&	Yes (for load)	Data reader providing text or binary param data

Outputs

Name	Type	Description
value	int / float / Mat / std::string	Stored parameter value, or the provided default if unset
type	int	Type tag of the stored value (0=null through 7=string)
return (load)	int	0 on success, non-zero on parse error

Usage Examples

Reading Parameters in a Custom Layer

#include "ncnn/layer.h"
#include "ncnn/paramdict.h"

class Convolution : public ncnn::Layer
{
public:
    virtual int load_param(const ncnn::ParamDict& pd)
    {
        // Parameter IDs follow ncnn's layer parameter convention
        num_output = pd.get(0, 0);       // number of output channels
        kernel_w = pd.get(1, 0);         // kernel width
        dilation_w = pd.get(2, 1);       // dilation (default: 1)
        stride_w = pd.get(3, 1);         // stride (default: 1)
        pad_left = pd.get(4, 0);         // left padding (default: 0)
        bias_term = pd.get(5, 0);        // has bias (default: 0)
        weight_data_size = pd.get(6, 0); // total weight count
        return 0;
    }

public:
    int num_output;
    int kernel_w;
    int dilation_w;
    int stride_w;
    int pad_left;
    int bias_term;
    int weight_data_size;
};

Programmatically Setting Parameters

#include "ncnn/paramdict.h"

ncnn::ParamDict pd;
pd.set(0, 64);       // set int param: num_output = 64
pd.set(1, 3);        // set int param: kernel_size = 3
pd.set(2, 1.5f);     // set float param: some_ratio = 1.5

// Check if a parameter is set
if (pd.type(3) == 0)
{
    // param 3 is not set (null)
}