[doc] Check and raise an error if the user is running Python from the…

… parent directory of the sam2 repo

If the user has "sam2/sam2" in their path, they are likey importing the repo itself as "sam2" rather than importing the "sam2" python package (i.e. "sam2/sam2" directory). This typically happens because the user is running Python from the parent directory that contains the sam2 repo they cloned.

In general, the user should not run Python from the parent dir when the repo is cloned into (same is true for e.g. Numpy repo that contains names like `numpy/numpy` where the module and the repo have the same name.

sam2/build_sam.py

@@ -5,12 +5,29 @@
 # LICENSE file in the root directory of this source tree.
 
 import logging
+import os
 
+import sam2
 import torch
 from hydra import compose
 from hydra.utils import instantiate
 from omegaconf import OmegaConf
 
+# Check if the user is running Python from the parent directory of the sam2 repo
+# (i.e. the directory where this repo is cloned into) -- this is not supported since
+# it could shadow the sam2 package and cause issues.
+if os.path.isdir(os.path.join(sam2.__path__[0], "sam2")):
+    # If the user has "sam2/sam2" in their path, they are likey importing the repo itself
+    # as "sam2" rather than importing the "sam2" python package (i.e. "sam2/sam2" directory).
+    # This typically happens because the user is running Python from the parent directory
+    # that contains the sam2 repo they cloned.
+    raise RuntimeError(
+        "You're likely running Python from the parent directory of the sam2 repo "
+        "(i.e. the directory where this repo https://github.com/facebookresearch/sam2 is cloned into). "
+        "This is not supported since the sam2 package could be shadowed by the repository name. "
+        "Please run Python from another directory (e.g. your home directory) after installation."
+    )
+
 HF_MODEL_ID_TO_FILENAMES = {
     "facebook/sam2-hiera-tiny": (
         "configs/sam2/sam2_hiera_t.yaml",