openpoints 0.1.0__py3-none-any.whl

openpoints/utils/registry.py

@@ -0,0 +1,294 @@
+# Acknowledgement: built upon mmcv
+import inspect
+import warnings
+from functools import partial
+import copy 
+
+
+class Registry:
+    """A registry to map strings to classes.
+    Registered object could be built from registry.
+    Example:
+        >>> MODELS = Registry('models')
+        >>> @MODELS.register_module()
+        >>> class ResNet:
+        >>>     pass
+        >>> resnet = MODELS.build(dict(NAME='ResNet'))
+    Please refer to https://mmcv.readthedocs.io/en/latest/registry.html for
+    advanced useage.
+    Args:
+        name (str): Registry name.
+        build_func(func, optional): Build function to construct instance from
+            Registry, func:`build_from_cfg` is used if neither ``parent`` or
+            ``build_func`` is specified. If ``parent`` is specified and
+            ``build_func`` is not given,  ``build_func`` will be inherited
+            from ``parent``. Default: None.
+        parent (Registry, optional): Parent registry. The class registered in
+            children registry could be built from parent. Default: None.
+        scope (str, optional): The scope of registry. It is the key to search
+            for children registry. If not specified, scope will be the name of
+            the package where class is defined, e.g. mmdet, mmcls, mmseg.
+            Default: None.
+    """
+
+    def __init__(self, name, build_func=None, parent=None, scope=None):
+        self._name = name
+        self._module_dict = dict()
+        self._children = dict()
+        self._scope = self.infer_scope() if scope is None else scope
+
+        # self.build_func will be set with the following priority:
+        # 1. build_func
+        # 2. parent.build_func
+        # 3. build_from_cfg
+        if build_func is None:
+            if parent is not None:
+                self.build_func = parent.build_func
+            else:
+                self.build_func = build_from_cfg
+        else:
+            self.build_func = build_func
+        if parent is not None:
+            assert isinstance(parent, Registry)
+            parent._add_children(self)
+            self.parent = parent
+        else:
+            self.parent = None
+
+    def __len__(self):
+        return len(self._module_dict)
+
+    def __contains__(self, key):
+        return self.get(key) is not None
+
+    def __repr__(self):
+        format_str = self.__class__.__name__ + \
+                     f'(name={self._name}, ' \
+                     f'items={self._module_dict})'
+        return format_str
+
+    @staticmethod
+    def infer_scope():
+        """Infer the scope of registry.
+        The name of the package where registry is defined will be returned.
+        Example:
+            # in mmdet/models/backbone/resnet.py
+            >>> MODELS = Registry('models')
+            >>> @MODELS.register_module()
+            >>> class ResNet:
+            >>>     pass
+            The scope of ``ResNet`` will be ``mmdet``.
+        Returns:
+            scope (str): The inferred scope name.
+        """
+        # inspect.stack() trace where this function is called, the index-2
+        # indicates the frame where `infer_scope()` is called
+        filename = inspect.getmodule(inspect.stack()[2][0]).__name__
+        split_filename = filename.split('.')
+        return split_filename[0]
+
+    @staticmethod
+    def split_scope_key(key):
+        """Split scope and key.
+        The first scope will be split from key.
+        Examples:
+            >>> Registry.split_scope_key('mmdet.ResNet')
+            'mmdet', 'ResNet'
+            >>> Registry.split_scope_key('ResNet')
+            None, 'ResNet'
+        Return:
+            scope (str, None): The first scope.
+            key (str): The remaining key.
+        """
+        split_index = key.find('.')
+        if split_index != -1:
+            return key[:split_index], key[split_index + 1:]
+        else:
+            return None, key
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def scope(self):
+        return self._scope
+
+    @property
+    def module_dict(self):
+        return self._module_dict
+
+    @property
+    def children(self):
+        return self._children
+
+    def get(self, key):
+        """Get the registry record.
+        Args:
+            key (str): The class name in string format.
+        Returns:
+            class: The corresponding class.
+        """
+        scope, real_key = self.split_scope_key(key)
+        if scope is None or scope == self._scope:
+            # get from self
+            if real_key in self._module_dict:
+                return self._module_dict[real_key]
+        else:
+            # get from self._children
+            if scope in self._children:
+                return self._children[scope].get(real_key)
+            else:
+                # goto root
+                parent = self.parent
+                while parent.parent is not None:
+                    parent = parent.parent
+                return parent.get(key)
+
+    def build(self, *args, **kwargs):
+        return self.build_func(*args, **kwargs, registry=self)
+
+    def _add_children(self, registry):
+        """Add children for a registry.
+        The ``registry`` will be added as children based on its scope.
+        The parent registry could build objects from children registry.
+        Example:
+            >>> models = Registry('models')
+            >>> mmdet_models = Registry('models', parent=models)
+            >>> @mmdet_models.register_module()
+            >>> class ResNet:
+            >>>     pass
+            >>> resnet = models.build(dict(NAME='mmdet.ResNet'))
+        """
+
+        assert isinstance(registry, Registry)
+        assert registry.scope is not None
+        assert registry.scope not in self.children, \
+            f'scope {registry.scope} exists in {self.name} registry'
+        self.children[registry.scope] = registry
+
+    def _register_module(self, module_class, module_name=None, force=False):
+        if not inspect.isclass(module_class):
+            raise TypeError('module must be a class, '
+                            f'but got {type(module_class)}')
+
+        if module_name is None:
+            module_name = module_class.__name__
+        if isinstance(module_name, str):
+            module_name = [module_name]
+        for name in module_name:
+            if not force and name in self._module_dict:
+                raise KeyError(f'{name} is already registered '
+                               f'in {self.name}')
+            self._module_dict[name] = module_class
+
+    def deprecated_register_module(self, cls=None, force=False):
+        warnings.warn(
+            'The old API of register_module(module, force=False) '
+            'is deprecated and will be removed, please use the new API '
+            'register_module(name=None, force=False, module=None) instead.')
+        if cls is None:
+            return partial(self.deprecated_register_module, force=force)
+        self._register_module(cls, force=force)
+        return cls
+
+    def register_module(self, name=None, force=False, module=None):
+        """Register a module.
+        A record will be added to `self._module_dict`, whose key is the class
+        name or the specified name, and value is the class itself.
+        It can be used as a decorator or a normal function.
+        Example:
+            >>> backbones = Registry('backbone')
+            >>> @backbones.register_module()
+            >>> class ResNet:
+            >>>     pass
+            >>> backbones = Registry('backbone')
+            >>> @backbones.register_module(name='mnet')
+            >>> class MobileNet:
+            >>>     pass
+            >>> backbones = Registry('backbone')
+            >>> class ResNet:
+            >>>     pass
+            >>> backbones.register_module(ResNet)
+        Args:
+            name (str | None): The module name to be registered. If not
+                specified, the class name will be used.
+            force (bool, optional): Whether to override an existing class with
+                the same name. Default: False.
+            module (type): Module class to be registered.
+        """
+        if not isinstance(force, bool):
+            raise TypeError(f'force must be a boolean, but got {type(force)}')
+        # NOTE: This is a walkaround to be compatible with the old api,
+        # while it may introduce unexpected bugs.
+        if isinstance(name, type):
+            return self.deprecated_register_module(name, force=force)
+
+        # raise the error ahead of time
+        if not (name is None or isinstance(name, str) or misc.is_seq_of(name, str)):
+            raise TypeError(
+                'name must be either of None, an instance of str or a sequence'
+                f'  of str, but got {type(name)}')
+
+        # use it as a normal method: x.register_module(module=SomeClass)
+        if module is not None:
+            self._register_module(
+                module_class=module, module_name=name, force=force)
+            return module
+
+        # use it as a decorator: @x.register_module()
+        def _register(cls):
+            self._register_module(
+                module_class=cls, module_name=name, force=force)
+            return cls
+
+        return _register
+
+
+def build_from_cfg(cfg, registry, default_args=None):
+    """Build a module from config dict.
+    Args:
+        cfg (edict): Config dict. It should at least contain the key "NAME".
+        registry (:obj:`Registry`): The registry to search the type from.
+    Returns:
+        object: The constructed object.
+    """
+    if not isinstance(cfg, dict):
+        raise TypeError(f'cfg must be a dict, but got {type(cfg)}')
+    if 'NAME' not in cfg:
+        if default_args is None or 'NAME' not in default_args:
+            raise KeyError(
+                '`cfg` or `default_args` must contain the key "NAME", '
+                f'but got {cfg}\n{default_args}')
+    if not isinstance(registry, Registry):
+        raise TypeError('registry must be an mmcv.Registry object, '
+                        f'but got {type(registry)}')
+
+    if not (isinstance(default_args, dict) or default_args is None):
+        raise TypeError('default_args must be a dict or None, '
+                        f'but got {type(default_args)}')
+
+    # if default_args is not None:
+    #     cfg = config.merge_new_config(cfg, default_args)
+
+    obj_type = cfg.get('NAME')
+
+    if isinstance(obj_type, str):
+        obj_cls = registry.get(obj_type)
+        if obj_cls is None:
+            raise KeyError(
+                f'{obj_type} is not in the {registry.name} registry')
+    elif inspect.isclass(obj_type):
+        obj_cls = obj_type
+    else:
+        raise TypeError(
+            f'type must be a str or valid type, but got {type(obj_type)}')
+    try:
+        obj_cfg = copy.deepcopy(cfg)
+        if default_args is not None:
+            obj_cfg.update(default_args) 
+        obj_cfg.pop('NAME')
+        return obj_cls(**obj_cfg)
+    except Exception as e:
+        # Normal TypeError does not print class name.
+        raise type(e)(f'{obj_cls.__name__}: {e}')

openpoints/utils/str2bool.py

@@ -0,0 +1,11 @@
+import argparse
+
+def str2bool(v):
+    if isinstance(v, bool):
+        return v
+    if v.lower() in ('yes', 'true', 't', 'y', '1'):
+        return True
+    elif v.lower() in ('no', 'false', 'f', 'n', '0'):
+        return False
+    else:
+        raise argparse.ArgumentTypeError('Boolean value expected.')

openpoints/utils/wandb.py

@@ -0,0 +1,88 @@
+import shutil
+import os
+import subprocess
+
+
+class WandbUrls:
+    def __init__(self, url):
+
+        hash = url.split("/")[-2]
+        project = url.split("/")[-3]
+        entity = url.split("/")[-4]
+
+        self.weight_url = url
+        self.log_url = "https://app.wandb.ai/{}/{}/runs/{}/logs".format(entity, project, hash)
+        self.chart_url = "https://app.wandb.ai/{}/{}/runs/{}".format(entity, project, hash)
+        self.overview_url = "https://app.wandb.ai/{}/{}/runs/{}/overview".format(entity, project, hash)
+        self.config_url = "https://app.wandb.ai/{}/{}/runs/{}/files/hydra-config.yaml".format(
+            entity, project, hash
+        )
+        self.overrides_url = "https://app.wandb.ai/{}/{}/runs/{}/files/overrides.yaml".format(entity, project, hash)
+
+    def __repr__(self):
+        msg = "=================================================== WANDB URLS ===================================================================\n"
+        for k, v in self.__dict__.items():
+            msg += "{}: {}\n".format(k.upper(), v)
+        msg += "=================================================================================================================================\n"
+        return msg
+
+
+class Wandb:
+    IS_ACTIVE = False
+
+    @staticmethod
+    def set_urls_to_model(model, url):
+        wandb_urls = WandbUrls(url)
+        model.wandb = wandb_urls
+
+    @staticmethod
+    def _set_to_wandb_args(wandb_args, cfg, name):
+        var = getattr(cfg.wandb, name, None)
+        if var:
+            if name == 'name':
+                var = var[:64]
+            wandb_args[name] = var
+
+    @staticmethod
+    def launch(cfg, launch: bool):
+        if launch:
+            import wandb
+
+            Wandb.IS_ACTIVE = True
+
+            wandb_args = {}
+            wandb_args["resume"] = "allow"
+            Wandb._set_to_wandb_args(wandb_args, cfg, "tags")
+            Wandb._set_to_wandb_args(wandb_args, cfg, "project")
+            Wandb._set_to_wandb_args(wandb_args, cfg, "name")
+            Wandb._set_to_wandb_args(wandb_args, cfg, "entity")
+            Wandb._set_to_wandb_args(wandb_args, cfg, "notes")
+            Wandb._set_to_wandb_args(wandb_args, cfg, "config")
+            Wandb._set_to_wandb_args(wandb_args, cfg, "id")
+            print(wandb_args)
+
+            try:
+                commit_sha = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode("ascii").strip()
+                gitdiff = subprocess.check_output(["git", "diff", "--", "':!notebooks'"]).decode()
+            except:
+                commit_sha = "n/a"
+                gitdiff = ""
+
+            config = wandb_args.get("config", {})
+            wandb_args["config"] = {
+                **config,
+                "run_path": os.getcwd(),
+                "commit": commit_sha,
+                "gitdiff": gitdiff
+            }
+            wandb.init(**wandb_args, sync_tensorboard=True)
+            wandb.save(os.path.join(os.getcwd(), cfg.cfg_path))
+
+    @staticmethod
+    def add_file(file_path: str):
+        if not Wandb.IS_ACTIVE:
+            raise RuntimeError("wandb is inactive, please launch first.")
+        import wandb
+
+        filename = os.path.basename(file_path)
+        shutil.copyfile(file_path, os.path.join(wandb.run.dir, filename))

openpoints-0.1.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: openpoints
+Version: 0.1.0
+Summary: OpenPoints: point cloud understanding models, layers, datasets, transforms, optimizers, and training utilities.
+Author: Guocheng Qian
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/guochengqian/openpoints
+Project-URL: Repository, https://github.com/guochengqian/openpoints
+Project-URL: Issues, https://github.com/guochengqian/PointNeXt/issues
+Keywords: point cloud,deep learning,pytorch,3d vision,PointNeXt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.10
+Requires-Dist: numpy>=1.20
+Requires-Dist: scipy>=1.7
+Requires-Dist: PyYAML>=5.4
+Requires-Dist: multimethod>=1.8
+Requires-Dist: termcolor>=1.1
+Requires-Dist: shortuuid>=1.0
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: tqdm>=4
+Requires-Dist: easydict>=1.9
+Requires-Dist: h5py>=3
+Requires-Dist: pandas>=1.3
+Requires-Dist: torchvision>=0.11
+Provides-Extra: data
+Requires-Dist: easydict>=1.9; extra == "data"
+Requires-Dist: h5py>=3; extra == "data"
+Requires-Dist: pandas>=1.3; extra == "data"
+Requires-Dist: torchvision>=0.11; extra == "data"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5; extra == "viz"
+Requires-Dist: pyvista>=0.38; extra == "viz"
+Provides-Extra: graph
+Requires-Dist: numba>=0.56; extra == "graph"
+Requires-Dist: ogb>=1.3; extra == "graph"
+Requires-Dist: atom3d>=0.2; extra == "graph"
+Requires-Dist: fast-pytorch-kmeans>=0.1; extra == "graph"
+Provides-Extra: tfds
+Requires-Dist: Pillow>=8; extra == "tfds"
+Requires-Dist: tensorflow>=2; extra == "tfds"
+Requires-Dist: tensorflow-datasets>=4; extra == "tfds"
+Provides-Extra: wandb
+Requires-Dist: wandb>=0.13; extra == "wandb"
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=4; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: all
+Requires-Dist: easydict>=1.9; extra == "all"
+Requires-Dist: h5py>=3; extra == "all"
+Requires-Dist: pandas>=1.3; extra == "all"
+Requires-Dist: torchvision>=0.11; extra == "all"
+Requires-Dist: matplotlib>=3.5; extra == "all"
+Requires-Dist: pyvista>=0.38; extra == "all"
+Requires-Dist: numba>=0.56; extra == "all"
+Requires-Dist: ogb>=1.3; extra == "all"
+Requires-Dist: atom3d>=0.2; extra == "all"
+Requires-Dist: fast-pytorch-kmeans>=0.1; extra == "all"
+Requires-Dist: Pillow>=8; extra == "all"
+Requires-Dist: tensorflow>=2; extra == "all"
+Requires-Dist: tensorflow-datasets>=4; extra == "all"
+Requires-Dist: wandb>=0.13; extra == "all"
+Dynamic: license-file
+
+# OpenPoints
+
+OpenPoints is a library built for fairly benchmarking and easily reproducing point-based methods for point cloud understanding. It is born in the course of [PointNeXt](https://github.com/guochengqian/PointNeXt) project and is used as an engine therein.
+
+**For any question related to OpenPoints, please open an issue in [PointNeXt](https://github.com/guochengqian/PointNeXt) repo.**
+
+OpenPoints currently supports reproducing the following models:
+- PointNet
+- DGCNN
+- DeepGCN
+- PointNet++
+- ASSANet
+- PointMLP
+- PointNeXt
+- Pix4Point
+- PointVector
+
+
+
+## Features
+
+1. **Extensibility**: supports many representative networks for point cloud understanding, such as *PointNet, DGCNN, DeepGCN, PointNet++, ASSANet, PointMLP*, and our ***PointNeXt***. More networks can be built easily based on our framework since **OpenPoints support a wide range of basic operations including graph convolutions, self-attention, farthest point sampling, ball query, *e.t.c***.
+
+2. **Ease of Use**: *Build* model, optimizer, scheduler, loss function,  and data loader *easily from cfg*. Train and validate different models on various tasks by simply changing the `cfg\*\*.yaml` file. 
+
+      ```
+   model = build_model_from_cfg(cfg.model)
+   criterion = build_criterion_from_cfg(cfg.criterion_args)
+   ```
+
+
+
+## Installation
+
+OpenPoints can be installed as the `openpoints` Python package:
+
+```bash
+pip install openpoints
+```
+
+The PyPI package installs the Python library (`import openpoints`) and the files needed by the datasets and configs. CUDA/C++ operators such as `pointnet2_batch_cuda`, `pointops_cuda`, `chamfer`, and `emd_cuda` are still built from a source checkout or source distribution for now because PyTorch/CUDA wheels must match the user's Python, PyTorch, CUDA, and platform versions.
+
+For full training/evaluation with CUDA ops, install from source after installing PyTorch:
+
+```bash
+git clone --recursive https://github.com/guochengqian/openpoints.git
+cd openpoints
+pip install -e .[data,viz,wandb]
+cd cpp/pointnet2_batch && python setup.py install && cd ../..
+cd cpp/pointops && python setup.py install && cd ../..
+cd cpp/chamfer_dist && python setup.py install && cd ../..
+cd cpp/emd && python setup.py install && cd ../..
+```
+
+If the `openpoints` name is unavailable on a package index mirror, the same code can be published as `openpoints-torch`; the import name remains `openpoints`.
+
+## Usage
+
+OpenPoints serves as the engine for PointNeXt. Please refer to [PointNeXt](https://github.com/guochengqian/PointNeXt) for complete training, evaluation, and model-zoo examples.
+
+
+
+## Citation
+
+If you use this library, please kindly acknowledge our work:
+```tex
+@Article{qian2022pointnext,
+  author  = {Qian, Guocheng and Li, Yuchen and Peng, Houwen and Mai, Jinjie and Hammoud, Hasan and Elhoseiny, Mohamed and Ghanem, Bernard},
+  title   = {PointNeXt: Revisiting PointNet++ with Improved Training and Scaling Strategies},
+  journal = {arXiv:2206.04670},
+  year    = {2022},
+}
+```
+