# Where the IMU samples come from.
#
# The recording is a plain .mcap file or a ROS 2 bag directory holding one next
# to a metadata.yaml, so both `--output-mcap` and `--output-rosbag` work.
input {
    # @recommended
    # Topic to read. Empty auto-detects the bag's only IMU topic.
    # @type string
    topic = ""

    # Which clock to build the sample timeline from.
    #   "header" the driver's own header.stamp, correct when the driver
    #            timestamps at the sensor.
    #   "log"    the MCAP log time, i.e. when the message was written.
    # @enum header, log
    # @type string
    time_source = "header"

    # Scale applied to the raw accelerometer samples before anything else.
    # A driver publishing in g rather than m/s^2 needs 9.80665 here.
    # @min_exclusive 0
    # @type number
    accel_scale = 1.0

    # Same for the gyroscope. A driver publishing deg/s needs 0.017453293.
    # @min_exclusive 0
    # @type number
    gyro_scale = 1.0

    # The stretch of the recording to use, in seconds from its first message
    # on the log clock. `to = 0s` means "to the end". Only this stretch of an
    # indexed MCAP is read, so a short window out of a long recording is fast.
    # `--from` and `--to` on the command line set the same two values.
    trim {
        # @type time
        # @min 0s
        from = 0s
        # @type time
        # @min 0s
        to = 0s
    }
}

output {
    # Key the IMU block is written under, matching Kalibr's imu0, imu1, ...
    # @type string
    name = "imu0"

    # `rostopic` field written into the YAML. Empty uses the input topic.
    # @type string
    rostopic = ""
}

# `dedrunk imu noise`: the stochastic parameters, from a long stationary recording.
#
# Kalibr uses these to size an estimator's covariances.
# Record at least three hours with the sensor completely undisturbed.
noise {
    # Cluster times the Allan deviation is evaluated at. Keep the longest below
    # a tenth of the recording, or its end of the curve is meaningless.
    cluster {
        # @recommended
        # Keep max below a tenth of the recording length.
        # @type time
        # @min_exclusive 0s
        min = 0.1s
        # @type time
        # @min_exclusive 0s
        max = 1000s

        # Number of logarithmically spaced cluster times between min and max.
        # @type integer
        # @min 2
        count = 100

        # Cluster pairs a tau needs before its point is trusted.
        # @type integer
        # @min 2
        min_pairs = 10
    }

    # Multiplier on the measured densities before they become the estimator
    # covariances printed for Pelorus. The YAML keeps the measured values.
    #
    # Allan variance is measured on a completely still sensor at constant
    # temperature. A moving robot has vibration, thermal drift and timing
    # jitter on top, and those dominate. The honest noise level in operation is
    # higher than the one on the bench, and no measurement says by how much.
    # The Kalibr wiki suggests 10x or more for MEMS parts.
    # @min_exclusive 0
    # @type number
    inflation = 10.0
}

# `dedrunk intrinsics imu`: the deterministic parameters, from a recording of the
# sensor held still in many orientations.
#
# These are what actually correct a measurement: scale, axis misalignment and
# bias. Minutes, not hours.
intrinsics {
    # @recommended
    # Local gravity magnitude in m/s^2.
    # @min_exclusive 0
    # @type number
    gravity = 9.80665

    # @recommended
    # "scale-misalignment" (9 parameters, >= 9 orientations, what Kalibr fits)
    # "scale-bias" (6 parameters, >= 6, for the six axis-aligned faces only)
    # @enum scale-misalignment, scale-bias
    # @type string
    accel_model = "scale-misalignment"

    # Also fit gyroscope scale and misalignment from the rotations between the
    # static stretches. Needs the moves to be about clearly different axes; if
    # they are not, the fit is dropped and only the bias is reported.
    # @type boolean
    gyro_scale = true

    # How a stationary stretch is told apart from a move.
    static {
        # @recommended
        # Stationary stretch at the start that measures the noise floor. The
        # recording has to begin with the sensor already at rest.
        # @type time
        # @min_exclusive 0s
        init = 4s

        # Shortest stretch that counts as a usable orientation. At least
        # `window`.
        # @type time
        # @min_exclusive 0s
        min_hold = 1s

        # Sliding window the still/moving decision is made over.
        # @type time
        # @min_exclusive 0s
        window = 0.2s

        # Multiple of the measured noise floor above which motion is declared.
        # Raise it on a wobbly surface, lower it if slow tilts slip through.
        # @min_exclusive 1
        # @type number
        threshold = 8.0
    }
}

# The Lidar-only trajectory `dedrunk extrinsics lidar-imu` and
# `dedrunk extrinsics lidar-camera` measure against.
#
# It must come from Lidar-only odometry: a Lidar-inertial or visual trajectory
# already assumes the extrinsic being measured.
trajectory {
    # @recommended
    # nav_msgs/msg/Odometry topic. Empty auto-detects the bag's only one.
    # @type string
    topic = ""
}

# `dedrunk extrinsics lidar-imu`: where the IMU sits relative to the Lidar.
lidar_imu {
    # @recommended
    # Local gravity magnitude in m/s^2. Also a check: the solver fits gravity
    # as a free vector, so a result far from this means the fit is wrong.
    # @min_exclusive 0
    # @type number
    gravity = 9.80665

    # Rate of the common timeline both streams are resampled onto, in Hz.
    # @min_exclusive 0
    # @type number
    resample_rate = 100.0

    # Largest clock difference to search for between the two sensors. The
    # search reserves this much data at each end of the overlap.
    # @type time
    # @min 0s
    max_time_offset = 0.5s

    # Half-width of the local polynomial fits the derivatives come from.
    # Differentiating a trajectory twice is the noisiest step; widen this on a
    # jittery trajectory, narrow it if real motion is being smoothed away.
    # @type time
    # @min_exclusive 0s
    smoothing_window = 0.1s

    # Angular rate in rad/s below which a sample carries no rotational
    # information and is left out of the rotation fit.
    # @min 0
    # @type number
    min_angular_rate = 0.05

    # Fraction of the best-excited direction below which a direction of the
    # translation is reported as unmeasured rather than returned as a number.
    # @min 0
    # @max_exclusive 1
    # @type number
    observability_threshold = 0.05
}

# Camera tracking, shared by `dedrunk extrinsics lidar-camera` and
# `dedrunk extrinsics camera-imu`.
#
# The camera is used as a gyroscope: features are tracked from image to image
# and the rotation between images is fitted to them, then matched against the
# other sensor's rotation for the extrinsic rotation and the clock offset. The
# intrinsics come from the driver's sensor_msgs/msg/CameraInfo topic, or from
# a camchain given with --intrinsics.
camera {
    # Largest clock difference to search for. The search reserves this much
    # data at each end of the overlap.
    # @type time
    # @min_exclusive 0s
    max_time_offset = 0.5s

    # Features tracked per image, and the smallest distance between two in
    # pixels. More features help in sparse scenes; the spacing keeps them from
    # piling onto one textured patch. The rotation fit needs 10 inliers per
    # image, so fewer than 20 features cannot work.
    # @type integer
    # @min 20
    features = 300
    # @min 1
    # @type number
    min_distance = 25.0

    # Largest reprojection error in pixels for a feature to count as following
    # the camera's motion. Features on nearby objects move with translation
    # too and fall out of the rotation fit here.
    # @min_exclusive 0
    # @type number
    ransac_threshold = 1.0

    # How well the motion has to determine the rotation: the third singular
    # value of the hand-eye system, iKalibr's check. Below it the recording
    # rotated about fewer than two axes and the result is refused.
    # @min 0
    # @type number
    min_singular_value = 0.25
}

# `dedrunk extrinsics lidar-camera`: the translation, and a refined rotation,
# from lining up Lidar depth edges with image edges (Levinson and Thrun, RSS
# 2013). Every few seconds the least blurred image is kept; the raw scans
# around it are deskewed with the trajectory, and the near side of every range
# jump between neighbours on a ring becomes an edge point. The search starts
# from the camera-as-gyroscope rotation, and refits on random halves of the
# keyframes report how well the scene determined the answer.
#
# Needs the raw sensor_msgs/msg/PointCloud2 scans, with a ring field, in the
# bag holding the images. Without them only the rotation and clock offset are
# measured.
lidar_camera {
    # @recommended
    # Raw scan topic. Empty auto-detects the image bag's only one.
    # @type string
    cloud_topic = ""

    # One keyframe image per this stretch, the least blurred of it.
    # @type time
    # @min_exclusive 0s
    keyframe_interval = 3s

    # Scans within this time of a keyframe are gathered for it. Longer fills
    # in a sparse Lidar, but leans harder on the trajectory being accurate.
    # @type time
    # @min_exclusive 0s
    accumulation = 0.5s

    # Smallest jump in metres from a point to its neighbour on the same ring
    # that makes the nearer point an object's outline.
    # @min_exclusive 0
    # @type number
    min_jump = 0.3

    # Keep a lever arm given with --lever-arm (from CAD, say) and refine only
    # the rotation.
    # @type boolean
    fix_translation = false
}

# `dedrunk intrinsics camera`: focal length, principal point and distortion
# from a recording of a calibration board (AprilGrid, checkerboard or ChArUco,
# described by a Kalibr target file).
#
# Move the board, or the camera, so it appears in every part of the image,
# including the corners, at several distances and tilted by 30-45 degrees in
# some views. Keep it sharp: slow motion or a short exposure.
camera_intrinsics {
    # One image per camera is examined this often. Neighbouring frames show
    # nearly the same view; looking at every one only costs time.
    # @type time
    # @min 0s
    sample_interval = 0.25s

    # Views the fit uses at most, picked so they cover the image evenly.
    # @type integer
    # @min 5
    max_views = 60
}

# Settings renamed when the commands were regrouped (`dedrunk extrinsics` became
# `dedrunk extrinsics lidar-imu`). They are read by nothing; a configuration
# that still sets one is refused with the new name, and an editor with the
# Ratslang language server offers the rename.
extrinsics {
    # @deprecated The Lidar-IMU settings moved to lidar_imu
    # @renamed_to trajectory.topic
    # @type string
    odometry_topic = ""
    # @deprecated The Lidar-IMU settings moved to lidar_imu
    # @renamed_to lidar_imu.gravity
    # @type number
    gravity = 9.80665
    # @deprecated The Lidar-IMU settings moved to lidar_imu
    # @renamed_to lidar_imu.resample_rate
    # @type number
    resample_rate = 100.0
    # @deprecated The Lidar-IMU settings moved to lidar_imu
    # @renamed_to lidar_imu.max_time_offset
    # @type time
    max_time_offset = 0.5s
    # @deprecated The Lidar-IMU settings moved to lidar_imu
    # @renamed_to lidar_imu.smoothing_window
    # @type time
    smoothing_window = 0.1s
    # @deprecated The Lidar-IMU settings moved to lidar_imu
    # @renamed_to lidar_imu.min_angular_rate
    # @type number
    min_angular_rate = 0.05
    # @deprecated The Lidar-IMU settings moved to lidar_imu
    # @renamed_to lidar_imu.observability_threshold
    # @type number
    observability_threshold = 0.05
}
