{"id":8875,"library":"basicsr","title":"BasicSR: Image and Video Super-Resolution Toolbox","description":"BasicSR is an open-source toolbox for image and video super-resolution and restoration, primarily built on PyTorch. It provides a flexible framework, common architectures, and training/testing scripts for various SOTA methods. The library sees active, though somewhat irregular, releases with a focus on adding new models and utility enhancements, currently at version 1.4.2.","status":"active","version":"1.4.2","language":"en","source_language":"en","source_url":"https://github.com/xinntao/BasicSR","tags":["deep learning","computer vision","super-resolution","image restoration","pytorch","video processing"],"install":[{"cmd":"pip install basicsr","lang":"bash","label":"Stable Release"},{"cmd":"pip install --upgrade basicsr","lang":"bash","label":"Upgrade"},{"cmd":"pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118\npip install basicsr","lang":"bash","label":"With PyTorch CUDA (example for CUDA 11.8)"}],"dependencies":[{"reason":"Core deep learning framework. Often needs specific CUDA version installation.","package":"torch","optional":false},{"reason":"Commonly used for image transformations and datasets, sometimes required for specific features like deform_conv2d.","package":"torchvision","optional":false},{"reason":"Fundamental package for numerical operations.","package":"numpy","optional":false},{"reason":"Used for image loading, saving, and processing.","package":"opencv-python","optional":false}],"imports":[{"note":"A utility class that simplifies loading and running Real-ESRGAN models.","symbol":"RealESRGANer","correct":"from basicsr.utils.realesrgan_utils import RealESRGANer"},{"note":"One of the common deep learning architectures used in super-resolution, e.g., by ESRGAN.","symbol":"RRDBNet","correct":"from basicsr.archs.rrdbnet_arch import RRDBNet"},{"note":"Utilities for converting images between NumPy arrays and PyTorch tensors.","symbol":"img2tensor","correct":"from basicsr.utils.img_util import img2tensor, tensor2img"},{"note":"Helper to download model checkpoints from URLs.","symbol":"load_file_from_url","correct":"from basicsr.utils.download_util import load_file_from_url"}],"quickstart":{"code":"import os\nimport cv2\nimport torch\nimport numpy as np\nfrom basicsr.archs.rrdbnet_arch import RRDBNet\nfrom basicsr.utils.realesrgan_utils import RealESRGANer\nfrom basicsr.utils.download_util import load_file_from_url\n\n# 1. Create a dummy low-resolution image (e.g., 64x64, 3 channels)\n# In a real application, this would be loaded from a file (e.g., cv2.imread)\ndummy_lr_img = np.random.randint(0, 256, (64, 64, 3), dtype=np.uint8)\n\n# 2. Define model parameters and download URL for a pre-trained Real-ESRGAN model\nmodel_scale = 4\nmodel_path_url = \"https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth\"\noutput_filename = \"dummy_sr_image.png\"\n\n# 3. Download the model weights\ntry:\n    # Model weights will be saved to a 'weights' directory by default\n    model_path = load_file_from_url(url=model_path_url, model_dir='weights', progress=True)\nexcept Exception as e:\n    print(f\"Could not download model from {model_path_url}: {e}\")\n    model_path = None # Set to None if download fails\n\nif model_path:\n    # 4. Initialize the RealESRGANer for inference\n    device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')\n\n    upsampler = RealESRGANer(\n        scale=model_scale,\n        model_path=model_path,\n        dni_weight=None, # Not used for standard RealESRGAN_x4plus\n        model_arch=RRDBNet,\n        tile=0, # Process image without tiling for small inputs\n        tile_pad=10,\n        pre_pad=0,\n        half=False, # Use float32, set to True for float16 inference if supported\n        device=device\n    )\n\n    # 5. Perform inference (enhance expects a NumPy array (HWC, BGR, uint8))\n    output_image, _ = upsampler.enhance(dummy_lr_img, outscale=model_scale)\n\n    # 6. Save the output image\n    cv2.imwrite(output_filename, output_image)\n    print(f\"Super-resolved image saved to {output_filename}\")\nelse:\n    print(\"Skipping quickstart inference due to model download failure or missing model path.\")\n\n# Clean up downloaded weights directory if desired (optional)\n# import shutil\n# if os.path.exists('weights'):\n#     shutil.rmtree('weights')","lang":"python","description":"This quickstart demonstrates how to programmatically perform super-resolution inference using a pre-trained Real-ESRGAN model. It covers creating a dummy input image, downloading the necessary model weights, initializing the `RealESRGANer` utility, and processing the image to save the super-resolved output. The example uses a common `RealESRGAN_x4plus` model from a public URL."},"warnings":[{"fix":"Review your code for any hardcoded paths or imports that might implicitly assume the old repository structure. Update to the latest version and verify functionality. Re-download any pre-trained models if paths change.","message":"As of v1.4.0, BasicSR officially moved under the 'XPixelGroup' organization. While direct breaking changes for user code might be minimal, internal paths or configuration assumptions could be affected for those updating from much older versions or directly referencing internal modules.","severity":"breaking","affected_versions":"<1.4.0"},{"fix":"Always ensure `torch` and `torchvision` are installed correctly for your specific CUDA version *before* installing `basicsr`. Use PyTorch's official installation instructions, e.g., `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118`.","message":"Older BasicSR versions (prior to v1.4.2) could encounter `ModuleNotFoundError` for `torch` if it wasn't pre-installed. This was due to `torch` not always being in `setup_requires`, leading to a race condition or failed imports during initial setup.","severity":"gotcha","affected_versions":"<1.4.2"},{"fix":"Carefully review your `.yml` configuration files for correct syntax, valid paths, and all necessary parameters as outlined in the official examples. Use the `force_yml` option (available since v1.3.4.2) for command-line overrides if needed.","message":"BasicSR heavily relies on YAML configuration files for training and testing. Incorrect file paths, malformed YAML syntax, or missing required parameters are common sources of errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to v1.4.1 or later. If using older versions and custom color conversion, consider manually implementing or verifying conversion logic with external libraries like `OpenCV` or `scikit-image`.","message":"A bug in `bgr2ycbcr` color conversion was fixed in v1.4.1. If you were using BasicSR's internal color conversion utilities in older versions for custom pipelines, your results might have been subtly incorrect.","severity":"gotcha","affected_versions":"<1.4.1"},{"fix":"Ensure your `torchvision` installation meets the minimum version requirement for the specific features you intend to use. Always follow the recommended PyTorch/Torchvision installation for your environment.","message":"Specific features like the official `torchvision.ops.deform_conv2d` require `torchvision>=0.9.0`. Using older `torchvision` versions might lead to compatibility issues or `AttributeError` for these advanced operators.","severity":"gotcha","affected_versions":"<1.3.4.2 (for this specific feature)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install PyTorch and Torchvision following official instructions, ensuring compatibility with your system's CUDA (if applicable). Example for CUDA 11.8: `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118`.","cause":"PyTorch (and often torchvision) is not installed, or is not accessible in the current Python environment, or installed incorrectly for your CUDA version.","error":"ModuleNotFoundError: No module named 'torch'"},{"fix":"Carefully review the specified YAML file for syntax errors, especially indentation and proper key-value pair formatting. Use a YAML linter if available.","cause":"Your YAML configuration file (e.g., options/train.yml) has an indentation error, a missing colon, or another syntax mistake.","error":"yaml.scanner.ScannerError: while scanning a simple key"},{"fix":"Verify that your YAML configuration file is correctly structured and contains all necessary keys for the operation (e.g., `name`, `network_g`, `path`). Double-check the file path provided to the `basicsr` script or function.","cause":"A required key is missing from your YAML configuration file, or the path to the YAML file is incorrect, leading to an empty or malformed dictionary being loaded.","error":"KeyError: 'name' (or similar for other config parameters)"},{"fix":"Ensure your input images (or tensors) match the expected format (e.g., HWC, BGR, uint8 for `cv2` operations or NCHW, float32, [0,1] or [-1,1] for PyTorch models). Check for sufficient GPU memory, especially with large models or batch sizes.","cause":"This often indicates an issue with input data (e.g., incorrect dimensions, data type, or value range) being passed to a model running on GPU, or a GPU memory issue.","error":"RuntimeError: CUDA error: device-side assert triggered"}]}