IT-1579: Refactor for use as submodule in IDPS repo (#63)

* Modify API to support being built as a part of the IDPS app, while still supporting standalone installation via pip
* Remove use of conda for local development and replace with venv module in python
* Update docs, removing recommendation for use with anaconda, and provide alternatives for using package on apple silicon
* Added support for python3.13

Author: nosheen-adil

.gitignore

@@ -1,6 +1,7 @@
 # secrets
 .ideas-github-token
 apiTestResults.xml
+venv/
 
 # IDE
 *.sublime-workspace

Makefile

@@ -24,31 +24,50 @@ ifndef THIRD_PARTY_DIR
 	THIRD_PARTY_DIR=third_party
 endif
 
-# Extract python version
-ifndef PYTHON_VERSION
-	PYTHON_VERSION=$(shell python -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
+# Virtual environment vars
+ifndef VENV_NAME
+	VENV_NAME=venv
 endif
 
 # Detect OS
 ifeq ($(OS), Windows_NT)
 	DETECTED_OS = windows
+	VENV_ACTIVATE = source ${VENV_NAME}/Scripts/activate
 else
+	VENV_ACTIVATE = source ${VENV_NAME}/bin/activate
 	UNAME_S = $(shell uname -s)
 	ifeq ($(UNAME_S), Linux)
 		DETECTED_OS = linux
 	else ifeq ($(UNAME_S), Darwin)
 		DETECTED_OS = mac
-		
+	endif
+endif
+
+ifndef PYTHON
+	PYTHON=python
+endif
+
+# Check if the directory exists using wildcard and conditional
+ifeq ($(wildcard $(VENV_NAME)/.),)
+  # Directory does not exist
+  PYTHON_VERSION=$(shell ${PYTHON} -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
+else
+  # Directory exists
+  PYTHON_VERSION=$(shell ${VENV_ACTIVATE} && ${PYTHON} -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
+endif
+
 # Set the macOS deployment version based on python version
-		ifeq ($(PYTHON_VERSION), 3.9)
-			_MACOSX_DEPLOYMENT_TARGET=10.11
-		else ifeq ($(PYTHON_VERSION), 3.10)
-			_MACOSX_DEPLOYMENT_TARGET=10.11
-		else ifeq ($(PYTHON_VERSION), 3.11)
-			_MACOSX_DEPLOYMENT_TARGET=10.11
-		else ifeq ($(PYTHON_VERSION), 3.12)
-			_MACOSX_DEPLOYMENT_TARGET=10.15
-		endif
+ifeq ($(DETECTED_OS), mac)
+	ifeq ($(PYTHON_VERSION), 3.9)
+		_MACOSX_DEPLOYMENT_TARGET=10.11
+	else ifeq ($(PYTHON_VERSION), 3.10)
+		_MACOSX_DEPLOYMENT_TARGET=10.11
+	else ifeq ($(PYTHON_VERSION), 3.11)
+		_MACOSX_DEPLOYMENT_TARGET=10.11
+	else ifeq ($(PYTHON_VERSION), 3.12)
+		_MACOSX_DEPLOYMENT_TARGET=10.15
+	else ifeq ($(PYTHON_VERSION), 3.13)
+		_MACOSX_DEPLOYMENT_TARGET=10.15
 	endif
 endif
 
@@ -82,22 +101,6 @@ else ifeq ($(DETECTED_OS), mac)
 	CMAKE_GENERATOR = Xcode
 endif
 
-# Virtual environment vars
-ifndef VENV_NAME
-	VENV_NAME=pyisx
-endif
-
-# Define cmake generator based on OS
-ifeq ($(DETECTED_OS), windows)
-	VENV_ACTIVATE = source '$(shell conda info --base)/Scripts/activate'
-else
-	VENV_ACTIVATE = source $(shell conda info --base)/bin/activate
-endif
-
-ifndef BUILD_API
-	BUILD_API=0
-endif
-
 check_os:
 	@echo "Verifying detected OS"
 ifndef DETECTED_OS
@@ -113,21 +116,19 @@ clean:
 	@rm -rf build
 	@rm -rf docs/build
 	@rm -rf wheelhouse
+	@rm -rf ${VENV_NAME}
 
 setup:
 	./scripts/setup -v --src ${REMOTE_DIR} --dst ${REMOTE_LOCAL_DIR} --remote-copy
 
-ifeq ($(DETECTED_OS), mac)
+ifeq ($(DETECTED_OS), windows)
 env:
-	CONDA_SUBDIR=osx-64 conda create -y -n $(VENV_NAME) python=$(PYTHON_VERSION) && \
-	$(VENV_ACTIVATE) $(VENV_NAME) && \
-	conda config --env --set subdir osx-64 && \
-	python -m pip install build
+	sh -c "${PYTHON} -m venv ${VENV_NAME}"
+	$(VENV_ACTIVATE) && python -m pip install '.[build,test,docs,deploy]'
 else
 env:
-	conda create -y -n $(VENV_NAME) python=$(PYTHON_VERSION) && \
-	$(VENV_ACTIVATE) $(VENV_NAME) && \
-	python -m pip install build
+	${PYTHON} -m venv ${VENV_NAME}
+	$(VENV_ACTIVATE) && python -m pip install '.[build,test,docs,deploy]'
 endif
 
 ifeq ($(DETECTED_OS), mac)
@@ -147,27 +148,26 @@ else ifeq ($(DETECTED_OS), mac)
 	cd $(BUILD_PATH) && \
 	xcodebuild -alltargets -configuration $(BUILD_TYPE) -project isx.xcodeproj CODE_SIGN_IDENTITY=""
 endif
+	$(VENV_ACTIVATE) && \
 	cd $(BUILD_PATH_BIN) && \
-	$(VENV_ACTIVATE) $(VENV_NAME) && \
 	python -m build
 
 rebuild: clean build
- 
-test:
-	$(VENV_ACTIVATE) $(VENV_NAME) && \
-	pip install --force-reinstall '$(shell ls $(BUILD_PATH_BIN)/dist/isx-*.whl)[test]' && \
+
+install:
+	$(VENV_ACTIVATE) && \
+	pip install --force-reinstall --no-deps '$(shell ls $(BUILD_PATH_BIN)/dist/isx-*.whl)'
+
+test: install
+	$(VENV_ACTIVATE) && \
 	cd build/Release && \
 	ISX_TEST_DATA_PATH='$(shell realpath $(TEST_DATA_DIR))' python -m pytest --disable-warnings -v -s --junit-xml=$(API_TEST_RESULTS_PATH) test $(TEST_ARGS)
 
-ifeq ($(BUILD_API), 1)
-docs: build
-	$(VENV_ACTIVATE) $(VENV_NAME) && \
-	pip install --force-reinstall '$(shell ls $(BUILD_PATH_BIN)/dist/isx-*.whl)[docs]'
-endif
 docs:
-	$(VENV_ACTIVATE) $(VENV_NAME) && \
+	$(VENV_ACTIVATE) && \
 	sphinx-build docs docs/build
 
+# Used for fixing linux wheel installs before deploying to pypi
 repair-linux:
 	docker run \
 		-v $(shell pwd):/io \
@@ -177,12 +177,10 @@ repair-linux:
 
 ifeq ($(DETECTED_OS), linux)
 deploy: repair-linux
-	$(VENV_ACTIVATE) $(VENV_NAME) && \
-	pip install twine && \
+	$(VENV_ACTIVATE) && \
 	twine upload '$(shell ls wheelhouse/isx-*.whl)'
 else
 deploy:
-	$(VENV_ACTIVATE) $(VENV_NAME) && \
-	pip install twine && \
+	$(VENV_ACTIVATE) && \
 	twine upload '$(shell ls $(BUILD_PATH_BIN)/dist/isx-*.whl)'
-endif
+endif

README.md

@@ -20,16 +20,7 @@ Pre-built binaries of this API can be installed from [PyPi](https://pypi.org/pro
 pip install isx
 ```
 
-> **Note:** For Apple Silicon (i.e., macOS arm64 architecture), the package is currently not natively supported. However, it's possible to use anaconda to configure an x86 environment and use the project.
-
-```bash
-CONDA_SUBDIR=osx-64 conda create -n <name> python=<python>
-conda activate <name>
-conda config --env --set subdir osx-64
-pip install isx
-```
-
-Replace `<name>` with a name for the conda environment, and `<python>` with the python version to use.
+> **Note**: Currently, pyisx is only supported for x86 architectures, which can be problematic, specifically on the newer Mac computers with Apple Silicon. For usage with Apple Silicon, the Rosetta software must be installed, and the Terminal app must be configured to use this software for automatic translation of x86 binaries to arm64. Read more [here](https://support.apple.com/en-us/102527) on how to configure Rosetta on Mac computers.
 
 ## Supported Platforms
 
@@ -60,43 +51,40 @@ Follow the setup instructions for the C++ [isxcore](https://github.com/inscopix/
 
 2. Setup python virtual environment
 
-Create a python virtual environment, specifying the desired python version.
-This guide uses anaconda for demonstration, but other tools like virtualenv or poetry can also be used.
+Create a python virtual environment using venv, specifying the desired python version.
 
 ```bash
-conda create -n <name> python=<python>
-conda activate <name>
+make env PYTHON=python3.13
 ```
 
-Replace `<name>` with a name for the conda environment, and `<python>` with the python version to use.
-
-> **Note**: On macOS systems with Apple Silicon, the conda environment is configured differently, since `isxcore` is currently only built for x86 architectures.
+> **Note**: Currently, pyisx is only supported for x86 architectures, which can be problematic, specifically on the newer Mac computers with Apple Silicon. For usage with Apple Silicon, the Rosetta software must be installed, and the Terminal app must be configured to use this software for automatic translation of x86 binaries to arm64. Read more [here](https://support.apple.com/en-us/102527) on how to configure Rosetta on Mac computers.
 
+In the Rosetta terminal, install Homebrew. This will install Homebrew to the `/usr/local` directory, indicating an x86 installation
 ```bash
-CONDA_SUBDIR=osx-64 conda create -n <name> python=<python>
-conda activate <name>
-conda config --env --set subdir osx-64
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 ```
 
-Replace `<name>` with a name for the conda environment, and `<python>` with the python version to use.
-
-3. Install build & test dependencies
-
-Inside the virtual environment install the following dependencies:
+Next, in Rosetta terminal, install the desired python version using the x86 installation of brew:
+```
+/usr/local/bin/brew install python@3.13
+```
 
-```bash
-conda install -y build pytest
+To verify the installation worked correctly run the following command:
+```
+python3.13 -c "import sysconfig; print(sysconfig.get_platform())"
 ```
 
-> **Note**: For python 3.12 the `build` package must be installed used `pip` instead.
+The output will be `macosx-13.0-x86_64` is running x86 version of python, otherwise the output will instead be `macosx-13.0-arm64` if running the arm version of python.
+
+3. Build the package
 
-4. Build the package
+Once the virtual environment is setup, the package can be built.
 
 ```bash
 make build THIRD_PARTY_DIR=/path/to/third/party/dir
 ```
 
-5. Run the unit tests
+4. Run the unit tests
 
 ```bash
 make test THIRD_PARTY_DIR=/path/to/third/party/dir TEST_DATA_DIR=/path/to/test/data/dir

docs/installation.md

@@ -7,22 +7,43 @@ Pre-built binaries of this API can be installed from [PyPi](https://pypi.org/pro
 pip install isx
 ```
 
+## Installation on Apple Silicon
+
 ::: {attention}
-For Apple Silicon (i.e., macOS with arm64 architecture), the package is currently not natively supported. However, it's possible to use [anaconda](https://www.anaconda.com/) to configure an x86 environment and use the project.
+Currently, pyisx is only supported for x86 architectures, which can be problematic, specifically on the newer Mac computers with Apple Silicon. The following section describes one option for how to use this package on newer Mac computers.
 :::
 
+For usage with Apple Silicon, the Rosetta software must be installed, and the Terminal app must be configured to use this software for automatic translation of x86 binaries to arm64. Read more [here](https://support.apple.com/en-us/102527) on how to configure Rosetta on Mac computers.
+
+Next, install an x86 version of python with the following steps.
+
+First, in the Rosetta terminal, install Homebrew, which is a package manager for macOS. This will install Homebrew to the `/usr/local` directory, indicating an x86 installation:
 ```bash
-CONDA_SUBDIR=osx-64 conda create -n <name> python=<python>
-conda activate <name>
-conda config --env --set subdir osx-64
-pip install isx
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+Next, in the Rosetta terminal, install the desired python version using the x86 installation of brew:
+```bash
+/usr/local/bin/brew install python@3.13
 ```
 
-Replace `<name>` with a name for the conda environment, and `<python>` with the python version to use.
+Verify the installation worked correctly by running the following command:
+```bash
+python3.13 -c "import sysconfig; print(sysconfig.get_platform())"
+```
+
+The output will be `macosx-13.0-x86_64` if running the x86 version of python, otherwise the output will instead be `macosx-13.0-arm64` if running the arm version of python.
+
+If the output indicates the x86 version of python, you can install the `pyisx` package.
+For example, the following snippet demonstrates how to create a [virtual environment](https://docs.python.org/3/library/venv.html) using the x86 version of python, and then install the pyisx package within the virtual environment.
+```bash
+python3.13 -m venv venv
+source venv/bin/activate && python -m pip install pyisx
+```
 
 ## Supported Platforms
 
-This package has been built and tested on the following operating systems, for python versions `3.9 - 3.12`:
+This package has been built and tested on the following operating systems, for python versions `3.9 - 3.13`:
 
 |  OS | Version | Architecture |
 |  --------- | ------- | ----- |

docs/overview.md

@@ -20,16 +20,9 @@ pip install isx
 ```
 
 ::: {attention}
-For Apple Silicon (i.e., macOS with arm64 architecture), the package is currently not natively supported. However, it's possible to use [anaconda](https://www.anaconda.com/) to configure an x86 environment and use the project.
+Currently, pyisx is only supported for x86 architectures, which can be problematic, specifically on the newer Mac computers with Apple Silicon. For usage with Apple Silicon, the Rosetta software must be installed, and the Terminal app must be configured to use this software for automatic translation of x86 binaries to arm64. Read more [here](https://support.apple.com/en-us/102527) on how to configure Rosetta on Mac computers.
 :::
 
-```bash
-CONDA_SUBDIR=osx-64 conda create -n <name> python=<python>
-conda activate <name>
-conda config --env --set subdir osx-64
-pip install isx
-```
-
 Please refer to the [Installation](#installation) guide for more details.
 
 ## File Types

isx/_internal.py

@@ -18,6 +18,10 @@
 _lib_dir = os.path.join(_this_dir, 'lib')
 _is_windows = os.name == 'nt'
 if _is_windows:
+    # Special case for windows
+    # If built apart of IDPS app, all dlls need to be in top-level app dir
+    if not os.path.exists(_lib_dir):
+        _lib_dir = os.path.join(_this_dir, '..')
     _cwd = os.getcwd()
     os.chdir(_lib_dir)
     _isx_lib_name = os.path.join(_lib_dir, 'isxpublicapi.dll')
@@ -1064,6 +1068,17 @@ def get_core_version():
         ctypes.c_double]
     c_api.isx_apply_cell_set.errcheck = _standard_errcheck
 
+    c_api.isx_apply_rois.argtypes = [
+        ctypes.c_int,
+        CharPtrPtr,
+        CharPtrPtr,
+        ctypes.c_int,
+        Int64Ptr,
+        Int64Ptr,
+        ctypes.c_bool,
+        CharPtrPtr]
+    c_api.isx_apply_rois.errcheck = _standard_errcheck
+
     c_api.isx_export_cell_contours.argtypes = [
         ctypes.c_int,
         CharPtrPtr,
@@ -1227,7 +1242,9 @@ def get_core_version():
         ctypes.c_char_p,
         ctypes.c_bool,
         ctypes.c_double,
-        ctypes.c_size_t]
+        ctypes.c_size_t,
+        ctypes.c_bool,
+        CharPtrPtr]
     c_api.isx_estimate_vessel_diameter.errcheck = _standard_errcheck
 
     c_api.isx_estimate_rbc_velocity.argtypes = [