انتقل إلى المحتوى

مرجع ل ultralytics/cfg/__init__.py

ملاحظه

هذا الملف متاح في https://github.com/ultralytics/ultralytics/ نقطة / الرئيسية /ultralytics/cfg/init.py. إذا اكتشفت مشكلة ، فيرجى المساعدة في إصلاحها من خلال المساهمة في طلب 🛠️ سحب. شكرا لك 🙏!



ultralytics.cfg.cfg2dict(cfg)

تحويل كائن تكوين إلى قاموس، سواء كان مسار ملف أو سلسلة أو كائن SimpleNamespace.

البارامترات:

اسم نوع وصف افتراضي
cfg str | Path | dict | SimpleNamespace

كائن التكوين المراد تحويله إلى قاموس.

مطلوب

ارجاع:

اسم نوع وصف
cfg dict

كائن التكوين بتنسيق القاموس.

شفرة المصدر في ultralytics/cfg/__init__.py
175 176 177 178 179 180 181 182 183 184 185 186 187188 189
def cfg2dict(cfg):
    """
    Convert a configuration object to a dictionary, whether it is a file path, a string, or a SimpleNamespace object.

    Args:
        cfg (str | Path | dict | SimpleNamespace): Configuration object to be converted to a dictionary.

    Returns:
        cfg (dict): Configuration object in dictionary format.
    """
    if isinstance(cfg, (str, Path)):
        cfg = yaml_load(cfg)  # load dict
    elif isinstance(cfg, SimpleNamespace):
        cfg = vars(cfg)  # convert to dict
    return cfg



ultralytics.cfg.get_cfg(cfg=DEFAULT_CFG_DICT, overrides=None)

تحميل بيانات التكوين ودمجها من ملف أو قاموس.

البارامترات:

اسم نوع وصف افتراضي
cfg str | Path | Dict | SimpleNamespace

بيانات التكوين.

DEFAULT_CFG_DICT
overrides str | Dict | optional

يتخطى في شكل اسم ملف أو قاموس. الافتراضي هو بلا.

None

ارجاع:

نوع وصف
SimpleNamespace

مساحة اسم وسيطات التدريب.

شفرة المصدر في ultralytics/cfg/__init__.py
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207208209 210 211 212 213 214 215 216217 218 219220 221 222 223224 225 226 227 228 229 230 231 232 233 234 235 236 237 238239 240 241 242 243 244 245 246 247 248
def get_cfg(cfg: Union[str, Path, Dict, SimpleNamespace] = DEFAULT_CFG_DICT, overrides: Dict = None):
    """
    Load and merge configuration data from a file or dictionary.

    Args:
        cfg (str | Path | Dict | SimpleNamespace): Configuration data.
        overrides (str | Dict | optional): Overrides in the form of a file name or a dictionary. Default is None.

    Returns:
        (SimpleNamespace): Training arguments namespace.
    """
    cfg = cfg2dict(cfg)

    # Merge overrides
    if overrides:
        overrides = cfg2dict(overrides)
        if "save_dir" not in cfg:
            overrides.pop("save_dir", None)  # special override keys to ignore
        check_dict_alignment(cfg, overrides)
        cfg = {**cfg, **overrides}  # merge cfg and overrides dicts (prefer overrides)

    # Special handling for numeric project/name
    for k in "project", "name":
        if k in cfg and isinstance(cfg[k], (int, float)):
            cfg[k] = str(cfg[k])
    if cfg.get("name") == "model":  # assign model to 'name' arg
        cfg["name"] = cfg.get("model", "").split(".")[0]
        LOGGER.warning(f"WARNING ⚠️ 'name=model' automatically updated to 'name={cfg['name']}'.")

    # Type and Value checks
    for k, v in cfg.items():
        if v is not None:  # None values may be from optional args
            if k in CFG_FLOAT_KEYS and not isinstance(v, (int, float)):
                raise TypeError(
                    f"'{k}={v}' is of invalid type {type(v).__name__}. "
                    f"Valid '{k}' types are int (i.e. '{k}=0') or float (i.e. '{k}=0.5')"
                )
            elif k in CFG_FRACTION_KEYS:
                if not isinstance(v, (int, float)):
                    raise TypeError(
                        f"'{k}={v}' is of invalid type {type(v).__name__}. "
                        f"Valid '{k}' types are int (i.e. '{k}=0') or float (i.e. '{k}=0.5')"
                    )
                if not (0.0 <= v <= 1.0):
                    raise ValueError(f"'{k}={v}' is an invalid value. " f"Valid '{k}' values are between 0.0 and 1.0.")
            elif k in CFG_INT_KEYS and not isinstance(v, int):
                raise TypeError(
                    f"'{k}={v}' is of invalid type {type(v).__name__}. " f"'{k}' must be an int (i.e. '{k}=8')"
                )
            elif k in CFG_BOOL_KEYS and not isinstance(v, bool):
                raise TypeError(
                    f"'{k}={v}' is of invalid type {type(v).__name__}. "
                    f"'{k}' must be a bool (i.e. '{k}=True' or '{k}=False')"
                )

    # Return instance
    return IterableSimpleNamespace(**cfg)



ultralytics.cfg.get_save_dir(args, name=None)

إرجاع save_dir كما تم إنشاؤه من وسيطات train/val/predict.

شفرة المصدر في ultralytics/cfg/__init__.py
251 252 253 254 255 256 257 258259 260 261262263
def get_save_dir(args, name=None):
    """Return save_dir as created from train/val/predict arguments."""

    if getattr(args, "save_dir", None):
        save_dir = args.save_dir
    else:
        from ultralytics.utils.files import increment_path

        project = args.project or (ROOT.parent / "tests/tmp/runs" if TESTS_RUNNING else RUNS_DIR) / args.task
        name = name or args.name or f"{args.mode}"
        save_dir = increment_path(Path(project) / name, exist_ok=args.exist_ok if RANK in (-1, 0) else True)

    return Path(save_dir)



ultralytics.cfg._handle_deprecation(custom)

وظيفة مضمنة للتعامل مع مفاتيح التكوين المهملة.

شفرة المصدر في ultralytics/cfg/__init__.py
266 267 268 269 270 271 272 273 274 275 276 277278279 280281282283
def _handle_deprecation(custom):
    """Hardcoded function to handle deprecated config keys."""

    for key in custom.copy().keys():
        if key == "boxes":
            deprecation_warn(key, "show_boxes")
            custom["show_boxes"] = custom.pop("boxes")
        if key == "hide_labels":
            deprecation_warn(key, "show_labels")
            custom["show_labels"] = custom.pop("hide_labels") == "False"
        if key == "hide_conf":
            deprecation_warn(key, "show_conf")
            custom["show_conf"] = custom.pop("hide_conf") == "False"
        if key == "line_thickness":
            deprecation_warn(key, "line_width")
            custom["line_width"] = custom.pop("line_thickness")

    return custom



ultralytics.cfg.check_dict_alignment(base, custom, e=None)

تتحقق هذه الوظيفة من وجود أي مفاتيح غير متطابقة بين قائمة التكوين المخصصة وقائمة التكوين الأساسية. لو تم العثور على أي مفاتيح غير متطابقة ، تقوم الوظيفة بطباعة مفاتيح مماثلة من القائمة الأساسية والخروج من البرنامج.

البارامترات:

اسم نوع وصف افتراضي
custom dict

قاموس لخيارات التكوين المخصصة

مطلوب
base dict

قاموس خيارات التكوين الأساسية

مطلوب
e Error

خطأ اختياري يتم تمريره بواسطة وظيفة الاتصال.

None
شفرة المصدر في ultralytics/cfg/__init__.py
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300301 302 303 304 305306307 308
def check_dict_alignment(base: Dict, custom: Dict, e=None):
    """
    This function checks for any mismatched keys between a custom configuration list and a base configuration list. If
    any mismatched keys are found, the function prints out similar keys from the base list and exits the program.

    Args:
        custom (dict): a dictionary of custom configuration options
        base (dict): a dictionary of base configuration options
        e (Error, optional): An optional error that is passed by the calling function.
    """
    custom = _handle_deprecation(custom)
    base_keys, custom_keys = (set(x.keys()) for x in (base, custom))
    mismatched = [k for k in custom_keys if k not in base_keys]
    if mismatched:
        from difflib import get_close_matches

        string = ""
        for x in mismatched:
            matches = get_close_matches(x, base_keys)  # key list
            matches = [f"{k}={base[k]}" if base.get(k) is not None else k for k in matches]
            match_str = f"Similar arguments are i.e. {matches}." if matches else ""
            string += f"'{colorstr('red', 'bold', x)}' is not a valid YOLO argument. {match_str}\n"
        raise SyntaxError(string + CLI_HELP_MSG) from e



ultralytics.cfg.merge_equals_args(args)

يدمج الوسيطات حول args '=' المعزولة في قائمة السلاسل. تأخذ الوظيفة في الاعتبار الحالات التي يكون فيها الأول تنتهي الوسيطة ب "=" أو تبدأ الثانية ب "=" ، وكذلك عندما يكون الوسط علامة يساوي.

البارامترات:

اسم نوع وصف افتراضي
args List[str]

قائمة بالسلاسل حيث يكون كل عنصر وسيطة.

مطلوب

ارجاع:

نوع وصف
List[str]

قائمة بالسلاسل حيث يتم دمج الوسيطات حول "=" المعزولة.

شفرة المصدر في ultralytics/cfg/__init__.py
311 312 313 314 315 316 317 318319 320 321 322 323 324 325 326 327 328329 330 331 332 333334
def merge_equals_args(args: List[str]) -> List[str]:
    """
    Merges arguments around isolated '=' args in a list of strings. The function considers cases where the first
    argument ends with '=' or the second starts with '=', as well as when the middle one is an equals sign.

    Args:
        args (List[str]): A list of strings where each element is an argument.

    Returns:
        (List[str]): A list of strings where the arguments around isolated '=' are merged.
    """
    new_args = []
    for i, arg in enumerate(args):
        if arg == "=" and 0 < i < len(args) - 1:  # merge ['arg', '=', 'val']
            new_args[-1] += f"={args[i + 1]}"
            del args[i + 1]
        elif arg.endswith("=") and i < len(args) - 1 and "=" not in args[i + 1]:  # merge ['arg=', 'val']
            new_args.append(f"{arg}{args[i + 1]}")
            del args[i + 1]
        elif arg.startswith("=") and i > 0:  # merge ['arg', '=val']
            new_args[-1] += arg
        else:
            new_args.append(arg)
    return new_args



ultralytics.cfg.handle_yolo_hub(args)

مقبض Ultralytics HUB واجهة سطر الأوامر (CLI) الأوامر.

تعالج هذه الوظيفة Ultralytics HUB CLI أوامر مثل تسجيل الدخول والخروج. يجب أن يطلق عليه عند تنفيذ برنامج نصي مع الحجج المتعلقة ب HUB المصادقه.

البارامترات:

اسم نوع وصف افتراضي
args List[str]

قائمة بوسيطات سطر الأوامر

مطلوب
مثل
python my_script.py hub login your_api_key
شفرة المصدر في ultralytics/cfg/__init__.py
337 338 339 340 341 342 343 344 345 346 347 348349 350 351 352 353 354 355 356 357358359 360
def handle_yolo_hub(args: List[str]) -> None:
    """
    Handle Ultralytics HUB command-line interface (CLI) commands.

    This function processes Ultralytics HUB CLI commands such as login and logout.
    It should be called when executing a script with arguments related to HUB authentication.

    Args:
        args (List[str]): A list of command line arguments

    Example:
        ```bash
        python my_script.py hub login your_api_key
        ```
    """
    from ultralytics import hub

    if args[0] == "login":
        key = args[1] if len(args) > 1 else ""
        # Log in to Ultralytics HUB using the provided API key
        hub.login(key)
    elif args[0] == "logout":
        # Log out from Ultralytics HUB
        hub.logout()



ultralytics.cfg.handle_yolo_settings(args)

مقبض YOLO واجهة سطر أوامر الإعدادات (CLI) الأوامر.

تعالج هذه الوظيفة YOLO اعدادات CLI أوامر مثل إعادة تعيين. يجب أن يطلق عليه عند تنفيذ برنامج نصي مع الحجج المتعلقة ب YOLO إدارة الإعدادات.

البارامترات:

اسم نوع وصف افتراضي
args List[str]

قائمة بوسيطات سطر الأوامر ل YOLO إدارة الإعدادات.

مطلوب
مثل
python my_script.py yolo settings reset
شفرة المصدر في ultralytics/cfg/__init__.py
363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387388389 390391392393 
def handle_yolo_settings(args: List[str]) -> None:
    """
    Handle YOLO settings command-line interface (CLI) commands.

    This function processes YOLO settings CLI commands such as reset.
    It should be called when executing a script with arguments related to YOLO settings management.

    Args:
        args (List[str]): A list of command line arguments for YOLO settings management.

    Example:
        ```bash
        python my_script.py yolo settings reset
        ```
    """
    url = "https://docs.ultralytics.com/quickstart/#ultralytics-settings"  # help URL
    try:
        if any(args):
            if args[0] == "reset":
                SETTINGS_YAML.unlink()  # delete the settings file
                SETTINGS.reset()  # create new settings
                LOGGER.info("Settings reset successfully")  # inform the user that settings have been reset
            else:  # save a new setting
                new = dict(parse_key_value_pair(a) for a in args)
                check_dict_alignment(SETTINGS, new)
                SETTINGS.update(new)

        LOGGER.info(f"💡 Learn about settings at {url}")
        yaml_print(SETTINGS_YAML)  # print the current settings
    except Exception as e:
        LOGGER.warning(f"WARNING ⚠️ settings error: '{e}'. Please see {url} for help.")



ultralytics.cfg.handle_explorer()

افتح الزر Ultralytics مستكشف واجهة المستخدم الرسومية.

شفرة المصدر في ultralytics/cfg/__init__.py
396 397 398399400 
def handle_explorer():
    """Open the Ultralytics Explorer GUI."""
    checks.check_requirements("streamlit")
    LOGGER.info(f"💡 Loading Explorer dashboard...")
    subprocess.run(["streamlit", "run", ROOT / "data/explorer/gui/dash.py", "--server.maxMessageSize", "2048"])



ultralytics.cfg.parse_key_value_pair(pair)

تحليل زوج واحد "مفتاح = قيمة" وإرجاع المفتاح والقيمة.

شفرة المصدر في ultralytics/cfg/__init__.py
403 404 405 406 407 408
def parse_key_value_pair(pair):
    """Parse one 'key=value' pair and return key and value."""
    k, v = pair.split("=", 1)  # split on first '=' sign
    k, v = k.strip(), v.strip()  # remove spaces
    assert v, f"missing '{k}' value"
    return k, smart_value(v)



ultralytics.cfg.smart_value(v)

قم بتحويل سلسلة إلى نوع أساسي مثل int و float و bool وما إلى ذلك.

شفرة المصدر في ultralytics/cfg/__init__.py
411 412 413 414 415 416 417418419 420 421 422 423
def smart_value(v):
    """Convert a string to an underlying type such as int, float, bool, etc."""
    v_lower = v.lower()
    if v_lower == "none":
        return None
    elif v_lower == "true":
        return True
    elif v_lower == "false":
        return False
    else:
        with contextlib.suppress(Exception):
            return eval(v)
        return v



ultralytics.cfg.entrypoint(debug='')

هذه الوظيفة هي ultralytics نقطة إدخال الحزمة ، وهي مسؤولة عن تحليل وسيطات سطر الأوامر التي تم تمريرها إلى الحزمة.

تسمح هذه الوظيفة بما يلي: - اجتياز إلزامي YOLO args كقائمة من السلاسل - تحديد المهمة المراد تنفيذها ، إما "كشف" أو "جزء" أو "تصنيف" - تحديد الوضع ، إما "القطار" أو "VAL" أو "الاختبار" أو "التنبؤ" - تشغيل أوضاع خاصة مثل "الشيكات" - تجاوز التجاوزات إلى تكوين الحزمة

يستخدم cfg الافتراضي للحزمة ويقوم بتهيئتها باستخدام التجاوزات التي تم تمريرها. ثم يسمي CLI وظيفة مع CFG المكونة

شفرة المصدر في ultralytics/cfg/__init__.py
def entrypoint(debug=""):
    """
    This function is the ultralytics package entrypoint, it's responsible for parsing the command line arguments passed
    to the package.

    This function allows for:
    - passing mandatory YOLO args as a list of strings
    - specifying the task to be performed, either 'detect', 'segment' or 'classify'
    - specifying the mode, either 'train', 'val', 'test', or 'predict'
    - running special modes like 'checks'
    - passing overrides to the package's configuration

    It uses the package's default cfg and initializes it using the passed overrides.
    Then it calls the CLI function with the composed cfg
    """
    args = (debug.split(" ") if debug else sys.argv)[1:]
    if not args:  # no arguments passed
        LOGGER.info(CLI_HELP_MSG)
        return

    special = {
        "help": lambda: LOGGER.info(CLI_HELP_MSG),
        "checks": checks.collect_system_info,
        "version": lambda: LOGGER.info(__version__),
        "settings": lambda: handle_yolo_settings(args[1:]),
        "cfg": lambda: yaml_print(DEFAULT_CFG_PATH),
        "hub": lambda: handle_yolo_hub(args[1:]),
        "login": lambda: handle_yolo_hub(args),
        "copy-cfg": copy_default_cfg,
        "explorer": lambda: handle_explorer(),
    }
    full_args_dict = {**DEFAULT_CFG_DICT, **{k: None for k in TASKS}, **{k: None for k in MODES}, **special}

    # Define common misuses of special commands, i.e. -h, -help, --help
    special.update({k[0]: v for k, v in special.items()})  # singular
    special.update({k[:-1]: v for k, v in special.items() if len(k) > 1 and k.endswith("s")})  # singular
    special = {**special, **{f"-{k}": v for k, v in special.items()}, **{f"--{k}": v for k, v in special.items()}}

    overrides = {}  # basic overrides, i.e. imgsz=320
    for a in merge_equals_args(args):  # merge spaces around '=' sign
        if a.startswith("--"):
            LOGGER.warning(f"WARNING ⚠️ '{a}' does not require leading dashes '--', updating to '{a[2:]}'.")
            a = a[2:]
        if a.endswith(","):
            LOGGER.warning(f"WARNING ⚠️ '{a}' does not require trailing comma ',', updating to '{a[:-1]}'.")
            a = a[:-1]
        if "=" in a:
            try:
                k, v = parse_key_value_pair(a)
                if k == "cfg" and v is not None:  # custom.yaml passed
                    LOGGER.info(f"Overriding {DEFAULT_CFG_PATH} with {v}")
                    overrides = {k: val for k, val in yaml_load(checks.check_yaml(v)).items() if k != "cfg"}
                else:
                    overrides[k] = v
            except (NameError, SyntaxError, ValueError, AssertionError) as e:
                check_dict_alignment(full_args_dict, {a: ""}, e)

        elif a in TASKS:
            overrides["task"] = a
        elif a in MODES:
            overrides["mode"] = a
        elif a.lower() in special:
            special[a.lower()]()
            return
        elif a in DEFAULT_CFG_DICT and isinstance(DEFAULT_CFG_DICT[a], bool):
            overrides[a] = True  # auto-True for default bool args, i.e. 'yolo show' sets show=True
        elif a in DEFAULT_CFG_DICT:
            raise SyntaxError(
                f"'{colorstr('red', 'bold', a)}' is a valid YOLO argument but is missing an '=' sign "
                f"to set its value, i.e. try '{a}={DEFAULT_CFG_DICT[a]}'\n{CLI_HELP_MSG}"
            )
        else:
            check_dict_alignment(full_args_dict, {a: ""})

    # Check keys
    check_dict_alignment(full_args_dict, overrides)

    # Mode
    mode = overrides.get("mode")
    if mode is None:
        mode = DEFAULT_CFG.mode or "predict"
        LOGGER.warning(f"WARNING ⚠️ 'mode' is missing. Valid modes are {MODES}. Using default 'mode={mode}'.")
    elif mode not in MODES:
        raise ValueError(f"Invalid 'mode={mode}'. Valid modes are {MODES}.\n{CLI_HELP_MSG}")

    # Task
    task = overrides.pop("task", None)
    if task:
        if task not in TASKS:
            raise ValueError(f"Invalid 'task={task}'. Valid tasks are {TASKS}.\n{CLI_HELP_MSG}")
        if "model" not in overrides:
            overrides["model"] = TASK2MODEL[task]

    # Model
    model = overrides.pop("model", DEFAULT_CFG.model)
    if model is None:
        model = "yolov8n.pt"
        LOGGER.warning(f"WARNING ⚠️ 'model' is missing. Using default 'model={model}'.")
    overrides["model"] = model
    stem = Path(model).stem.lower()
    if "rtdetr" in stem:  # guess architecture
        from ultralytics import RTDETR

        model = RTDETR(model)  # no task argument
    elif "fastsam" in stem:
        from ultralytics import FastSAM

        model = FastSAM(model)
    elif "sam" in stem:
        from ultralytics import SAM

        model = SAM(model)
    else:
        from ultralytics import YOLO

        model = YOLO(model, task=task)
    if isinstance(overrides.get("pretrained"), str):
        model.load(overrides["pretrained"])

    # Task Update
    if task != model.task:
        if task:
            LOGGER.warning(
                f"WARNING ⚠️ conflicting 'task={task}' passed with 'task={model.task}' model. "
                f"Ignoring 'task={task}' and updating to 'task={model.task}' to match model."
            )
        task = model.task

    # Mode
    if mode in ("predict", "track") and "source" not in overrides:
        overrides["source"] = DEFAULT_CFG.source or ASSETS
        LOGGER.warning(f"WARNING ⚠️ 'source' is missing. Using default 'source={overrides['source']}'.")
    elif mode in ("train", "val"):
        if "data" not in overrides and "resume" not in overrides:
            overrides["data"] = DEFAULT_CFG.data or TASK2DATA.get(task or DEFAULT_CFG.task, DEFAULT_CFG.data)
            LOGGER.warning(f"WARNING ⚠️ 'data' is missing. Using default 'data={overrides['data']}'.")
    elif mode == "export":
        if "format" not in overrides:
            overrides["format"] = DEFAULT_CFG.format or "torchscript"
            LOGGER.warning(f"WARNING ⚠️ 'format' is missing. Using default 'format={overrides['format']}'.")

    # Run command in python
    getattr(model, mode)(**overrides)  # default args from model

    # Show help
    LOGGER.info(f"💡 Learn more at https://docs.ultralytics.com/modes/{mode}")



ultralytics.cfg.copy_default_cfg()

انسخ ملف تكوين افتراضي جديد وأنشأه مع إلحاق "_copy" باسمه.

شفرة المصدر في ultralytics/cfg/__init__.py
575 576 577 578 579 580 581 582
def copy_default_cfg():
    """Copy and create a new default configuration file with '_copy' appended to its name."""
    new_file = Path.cwd() / DEFAULT_CFG_PATH.name.replace(".yaml", "_copy.yaml")
    shutil.copy2(DEFAULT_CFG_PATH, new_file)
    LOGGER.info(
        f"{DEFAULT_CFG_PATH} copied to {new_file}\n"
        f"Example YOLO command with this new custom cfg:\n    yolo cfg='{new_file}' imgsz=320 batch=8"
    )





تم إنشاء 2023-11-12, اخر تحديث 2024-01-10
المؤلفون: أيوشكسيل (1) ، جلين جوشر (3) ، يضحك س (1)