Package: refinenet
~Please note this is only abetarelease at this stage~RefineNet: high-res semantic image segmentationRefineNet is a generic multi-path refinement network for high-resolution semantic image segmentation and general dense prediction tasks on images. It achieves high-resolution prediction by explicitly exploiting all the information available along the down-sampling process and using long-range residual connections.This repository contains an open-source implementation of RefineNet in Python, with both the official and lightweight network models from our publications. The package provides PyTorch implementations for using training, evaluation, and prediction in your own systems. The package is easily installable withconda, and can also be installed viapipif you'd prefer to manually handle dependencies.Our code is free to use, and licensed under BSD-3. We simply ask that youcite our workif you use RefineNet in your own research.Related resourcesThis repository brings the work from a number of sources together. Please see the links below for further details:our original paper:"RefineNet: Multi-Path Refinement Networks for High-Resolution Semantic Segmentation"our paper introducing the lightweight version:"Light-Weight RefineNet for Real-Time Semantic Segmentation"the original MATLAB implementation:https://github.com/guosheng/refinenetVladimir Nekrasov's PyTorch port of RefineNet:https://github.com/DrSleep/refinenet-pytorchVladimir Nekrasov's PyTorch port of lightweight RefineNet:https://github.com/DrSleep/light-weight-refinenetInstalling RefineNetWe offer three methods for installing RefineNet:Through our Conda package: single command installs everything including system dependencies (recommended)Through our pip package: single command installs RefineNet and Python dependences, you take care of system dependenciesDirectly from source: allows easy editing and extension of our code, but you take care of building and all dependenciesCondaThe only requirement is that you haveConda installedon your system, andNVIDIA drivers installedif you want CUDA acceleration. We provide Conda packages throughConda Forge, which recommends adding their channel globally with strict priority:conda config --add channels conda-forge
conda config --set channel_priority strictOnce you have access to theconda-forgechannel, RefineNet is installed by running the following from inside aConda environment:u@pc:~$ conda install refinenetWe don't explicitly lock the PyTorch installation to a CUDA-enabled version to maximise compatibility with our users' possible setups. If you wish to ensure a CUDA-enabled PyTorch is installed, please use the following installation line instead:u@pc:~$ conda install pytorch=*=*cuda* refinenetYou can see a list of our Conda dependencies in theRefineNet feedstock's recipe.PipBefore installing viapip, you must have the following system dependencies installed if you want CUDA acceleration:NVIDIA driversCUDAThen RefineNet, and all its Python dependencies can be installed via:u@pc:~$ pip install refinenetFrom sourceInstalling from source is very similar to thepipmethod above due to RefineNet only containing Python code. Simply clone the repository, enter the directory, and install viapip:u@pc:~$ pip install -e .Note: the editable mode flag (-e) is optional, but allows you to immediately use any changes you make to the code in your local Python ecosystem.We also include scripts in the./scriptsdirectory to support running RefineNet without anypipinstallation, but this workflow means you need to handle all system and Python dependencies manually.Using RefineNetRefineNet can be used either entirely from the command line, or through its Python API. Both call the same underlying implementation, and as such offer equivalent functionality. We provide both options to facilitate use across a wide range of applications. See below for details of each method.RefineNet from the command lineWhen installed, either viapiporconda, arefinenetexecutable is made available on your systemPATH(the scripts in the./scriptsdirectory can be used as an alternative if not installing via a package manager).Therefinenetexecutable provides access to all functionality, including training, evaluation, and prediction. See the--helpflags for details on what the command line utility can do, and how it can be configured:u@pc:~$ refinenet --helpu@pc:~$ refinenet train --helpu@pc:~$ refinenet evaluate --helpu@pc:~$ refinenet predict --helpRefineNet Python APIRefineNet can also be used like any other Python package through its API. The API consists of aRefineNetclass with three main functions for training, evaluation, and prediction. Below are some examples to help get you started with RefineNet:fromrefinenetimportRefineNet# Initialise a full RefineNet network with no pre-trained modelr=RefineNet()# Initialise a standard RefineNet network with a model pre-trained on NYUr=RefineNet(model_type='full',load_pretrained='nyu')# Initialise a lightweight RefineNet network with 40 classesr=RefineNet(model='lightweight',num_classes=40)# Load a previous snapshot from a 152 layer networkr=RefineNet(load_snapshot='/path/to/snapshot',num_resnet_layers=152)# Train a new model on the NYU dataset with a custom learning rater.train('nyu',learning_rate=0.0005)# Train a model with the adam optimiser & 8 workers, saving output to ~/outputr.train('voc',optimiser_type='adam',num_workers=8,output_directory='~/output')# Get a predicted segmentation as a NumPy image, given an input NumPy imagesegmentation_image=r.predict(image=my_image)# Save a segmentation image to file, given an image from another image filer.predict(image_file='/my/prediction.jpg',output_file='/my/segmentation/image.jpg')# Evaluate your model's performance on the voc dataset, & save the results with# imagesr.evaluate('voc',output_directory='/my/results.json',output_images=True)Citing our workIf using RefineNet in your work, please citeour original CVPR paper:@InProceedings{Lin_2017_CVPR,author={Lin, Guosheng and Milan, Anton and Shen, Chunhua and Reid, Ian},title={RefineNet: Multi-Path Refinement Networks for High-Resolution Semantic Segmentation},booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},month={July},year={2017}}Please also citeour BMVC paperon Light-Weight RefineNet if using the lightweight models:@article{nekrasov2018light,title={Light-weight refinenet for real-time semantic segmentation},author={Nekrasov, Vladimir and Shen, Chunhua and Reid, Ian},journal={arXiv preprint arXiv:1810.03272},year={2018}}