What causes "大地图特征点匹配引发异常：{ex.Message}" in babalae/better-genshin-impact?

Inspect the inner exception (ex.InnerException) for the true root cause.

babalae/better-genshin-impact · error · MapPositionNotRecognizedException

大地图特征点匹配引发异常：{ex.Message}

Error message

大地图特征点匹配引发异常：{ex.Message}

What it means

Thrown by RecognizeBigMapCenterPoint as a wrapper when the underlying map.GetBigMapPosition call throws any exception. The original exception is captured as the inner exception and its message is appended. This converts arbitrary matching/processing errors into a MapPositionNotRecognizedException so callers can handle recognition failures uniformly.

Source

Thrown at BetterGenshinImpact/GameTask/AutoTrackPath/TpTask.cs:2166

        else
        {
            throw new InvalidOperationException("当前不在地图界面");
        }
    }

    private Point2f RecognizeBigMapCenterPoint(string mapName, Mat greyMat, Point2f? expectedCenterPoint = null)
    {
        Point2f p;
        try
        {
            var map = MapManager.GetMap(mapName, _mapMatchingMethod);
            p = expectedCenterPoint is Point2f expectedCenter
                ? map.GetBigMapPosition(greyMat, map.ConvertGenshinMapCoordinatesToImageCoordinates(expectedCenter))
                : map.GetBigMapPosition(greyMat);
        }
        catch (Exception ex)
        {
            throw new MapPositionNotRecognizedException("大地图特征点匹配引发异常：" + ex.Message, ex);
        }

        if (p.IsEmpty())
        {
            throw new MapPositionNotRecognizedException("大地图特征点匹配识别位置失败");
        }

        // 提瓦特大陆由于用的256的图，需要做特殊逻辑
        var (x, y) = (p.X, p.Y);
        if (mapName == MapTypes.Teyvat.ToString())
        {
            (x, y) = (p.X * TeyvatMap.BigMap256ScaleTo2048, p.Y * TeyvatMap.BigMap256ScaleTo2048);
        }

        return MapManager.GetMap(mapName, _mapMatchingMethod).ConvertImageCoordinatesToGenshinMapCoordinates(new Point2f(x, y))!.Value;
    }

    /// <summary>

View on GitHub (pinned to a7cb36712d)

Solutions

Inspect the inner exception (ex.InnerException) for the true root cause.
Ensure map assets for the specified mapName are downloaded and loaded.
Verify the OpenCV/EmguCV native libraries are correctly deployed.
Validate that expectedCenterPoint (if provided) is within the map's valid coordinate bounds.
Check logs for asset loading failures during startup.

Defensive patterns

Strategy: try-catch

Try / catch

try
{
    // RecognizeBigMapCenterPoint is private; catch at the caller level
catch (MapPositionNotRecognizedException ex) when (ex.Message.StartsWith("大地图特征点匹配引发异常"))
{
    Logger.LogError($"Feature matching threw: {ex.InnerException?.Message}");
    // Inspect inner exception for root cause (OpenCV error, missing asset, etc.)
}

Prevention

Always inspect the InnerException to find the true root cause.
Ensure map assets and native OpenCV libraries are correctly loaded.
Validate expectedCenterPoint coordinates are within valid bounds before calling.
Check startup logs for asset loading errors.

When it happens

Trigger: Called from RecognizeBigMapCenterPoint. map.GetBigMapPosition(greyMat, ...) or map.ConvertGenshinMapCoordinatesToImageCoordinates throws — could be an OpenCV error, null reference from missing map data, argument exception from invalid coordinates, etc.

Common situations: Map matching assets not loaded or corrupted; OpenCV/EmguCV runtime error; the expectedCenterPoint coordinate is out of valid range for the conversion; internal data structure not initialized for the requested mapName.

Related errors

AI-assisted analysis of babalae/better-genshin-impact@a7cb36712d (2026-08-13). Data as JSON: /api/errors/fba72cbe67f75939. Report an issue: GitHub.