Lab 1¶

Getting Started with IBM Geospatial Studio

⏱️ Estimated Duration: 10 minutes
📊 Difficulty Level: Beginner

📥 Getting the Lab Materials

Getting the Lab Materials: Clone the repository:

git clone https://github.com/terrastackai/geospatial-studio.git
cd geospatial-studio/workshop/docs/notebooks
jupyter notebook lab1-getting-started.ipynb

Overview¶

Welcome to IBM Geospatial Studio! This lab will introduce you to the three ways you can interact with the platform:

🖥️ User Interface (UI) - Visual, browser-based interaction
🔌 REST API - Direct HTTP requests for automation
🐍 Python SDK - Programmatic access via Python

By the end of this lab, you will:

Understand the Studio architecture and components
Navigate the Studio UI and generate API keys
Install and configure the Python SDK
Make your first API calls to explore the platform
Understand the relationship between UI, API, and SDK

Prerequisites¶

Geospatial Studio deployed and accessible (see Pre-work section)
Python 3.11+ installed
Jupyter notebook environment
Access to the Studio UI URL

Part 1: Understanding Geospatial Studio¶

What is Geospatial Studio?¶

IBM Geospatial Studio is a comprehensive platform for:

Fine-tuning geospatial foundation models
Running inference on satellite imagery
Managing datasets and model artifacts
Visualizing results on interactive maps

Key Components¶

┌─────────────────────────────────────────────────────────┐
│                    Studio UI (Port 4180)                │
│              Browser-based User Interface               │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────┐
│              Gateway API (Port 4181)                    │
│         REST API for all platform operations            │
└────────────────────────┬────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
┌───────▼──────┐  ┌──────▼──────┐  ┌─────▼──────┐
│  PostgreSQL  │  │   MinIO     │  │  MLflow    │
│  (Metadata)  │  │  (Storage)  │  │ (Tracking) │
└──────────────┘  └─────────────┘  └────────────┘

Three Ways to Interact¶

Method	Use Case	Pros	Cons
UI	Exploration, visualization	Easy to use, visual feedback	Manual, not scriptable
API	Automation, CI/CD	Direct control, language-agnostic	Requires HTTP knowledge
SDK	Data science workflows	Pythonic, integrated with notebooks	Python-only

Part 2: Exploring the Studio UI¶

Step 1: Access the UI¶

Open your browser and navigate to your Studio UI URL:
- Local deployment: https://localhost:4180
- Cluster deployment: Your configured ingress URL
Login with your credentials (configured during deployment)

Step 2: Navigate the Main Sections¶

The Studio UI has several main sections:

🏠 Home Page¶

Quick access to main features
Recent activity
API key management

📊 Data Catalog¶

Browse and manage datasets
Upload new data
View dataset metadata

🤖 Model Catalog¶

Browse available models
View fine-tuned models
Model performance metrics

🎯 Inference¶

Run models on new areas
View inference results
Interactive map visualization

⚙️ Fine-tuning¶

Create new fine-tuning jobs
Monitor training progress
View training metrics

Step 3: Generate an API Key¶

Important: You'll need an API key to use the SDK and API.

Click on your user profile (top right corner)
Select "Manage API Keys"
Click "Generate New Key"
Copy the key immediately (you won't be able to see it again!)
Store it securely

Note: Each user can have a maximum of 2 active API keys at a time.

Step 4: Explore the Empty Studio¶

Since this is a fresh deployment, you'll notice:

✅ Data Catalog: Empty (no datasets yet)
✅ Model Catalog: Empty (no fine-tuned models yet)
✅ Inference: No results yet

This is expected! In the next labs, we'll populate the studio with data and models.

Part 3: Setting Up the Python SDK¶

Step 1: Install the SDK¶

The geostudio package provides a Python interface to the Studio API.

In [ ]:

Copied!

# Install the geostudio SDK
!pip install geostudio --quiet
# Install the geostudio SDK
!pip install geostudio --quiet

Step 2: Verify Installation¶

In [ ]:

Copied!

import geostudio
from geostudio import Client

print(f"✓ geostudio SDK installed successfully!")
print(f"✓ Client class available: {Client is not None}")
import geostudio
from geostudio import Client

print(f"✓ geostudio SDK installed successfully!")
print(f"✓ Client class available: {Client is not None}")

Part 4: Configuring SDK Authentication¶

Method 1: Using a Configuration File (Recommended)¶

Create a .geostudio_config_file with your credentials:

In [ ]:

Copied!





# Create configuration file
# Replace with your actual values!

config_content = """GEOSTUDIO_API_KEY=your-api-key-here
BASE_STUDIO_UI_URL=https://localhost:4180
"""

# Write to file
with open('.geostudio_config_file', 'w') as f:
    f.write(config_content)

print("✓ Configuration file created")
print("⚠️  Remember to replace 'your-api-key-here' with your actual API key!")
# Create configuration file
# Replace with your actual values!

config_content = """GEOSTUDIO_API_KEY=your-api-key-here
BASE_STUDIO_UI_URL=https://localhost:4180
"""

# Write to file
with open('.geostudio_config_file', 'w') as f:
    f.write(config_content)

print("✓ Configuration file created")
print("⚠️  Remember to replace 'your-api-key-here' with your actual API key!")

Security Note:

Never commit .geostudio_config_file to version control
Add it to your .gitignore
Keep your API keys secure

Part 5: Connecting to Studio with the SDK¶

Initialize the Client¶

In [ ]:

Copied!

# Disable SSL warnings for local development
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

from geostudio import Client

# Initialize client using config file
client = Client(geostudio_config_file=".geostudio_config_file")

print("✓ Successfully connected to Geospatial Studio!")
# Disable SSL warnings for local development
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

from geostudio import Client

# Initialize client using config file
client = Client(geostudio_config_file=".geostudio_config_file")

print("✓ Successfully connected to Geospatial Studio!")

Part 6: Your First SDK Operations¶

Check Platform Status¶

Let's verify the connection by checking what's in our fresh Studio deployment:

In [ ]:

Copied!





# List datasets (should be empty on fresh deployment)
try:
    response = client.list_datasets()
    print("API Response:")
    print(response)
    print()
    
    # Extract results from paginated response
    datasets = response.get('results', [])
    total = response.get('total_records', 0)
    
    print(f"📊 Datasets in catalog: {total}")
    
    if total == 0:
        print("   ✓ This is expected for a fresh deployment!")
        print("   ℹ️  We'll add datasets in Lab 4")
    else:
        print("   Found existing datasets:")
        for ds in datasets[:5]:  # Show first 5
            print(f"   - {ds.get('name', 'Unknown')}")
except Exception as e:
    print(f"❌ Error listing datasets: {e}")
# List datasets (should be empty on fresh deployment)
try:
    response = client.list_datasets()
    print("API Response:")
    print(response)
    print()
    
    # Extract results from paginated response
    datasets = response.get('results', [])
    total = response.get('total_records', 0)
    
    print(f"📊 Datasets in catalog: {total}")
    
    if total == 0:
        print("   ✓ This is expected for a fresh deployment!")
        print("   ℹ️  We'll add datasets in Lab 4")
    else:
        print("   Found existing datasets:")
        for ds in datasets[:5]:  # Show first 5
            print(f"   - {ds.get('name', 'Unknown')}")
except Exception as e:
    print(f"❌ Error listing datasets: {e}")

In [ ]:

Copied!





# List fine-tuned models (tunes) - should be empty on fresh deployment
try:
    response = client.list_tunes()
    print("API Response:")
    print(response)
    print()
    
    # Extract results from paginated response
    tunes = response.get('results', [])
    total = response.get('total_records', 0)
    
    print(f"🤖 Fine-tuned models (tunes): {total}")
    
    if total == 0:
        print("   ✓ This is expected for a fresh deployment!")
        print("   ℹ️  We'll upload model checkpoints in Lab 3")
    else:
        print("   Found existing tunes:")
        for tune in tunes[:5]:  # Show first 5
            print(f"   - {tune.get('name', 'Unknown')}")
except Exception as e:
    print(f"❌ Error listing tunes: {e}")
# List fine-tuned models (tunes) - should be empty on fresh deployment
try:
    response = client.list_tunes()
    print("API Response:")
    print(response)
    print()
    
    # Extract results from paginated response
    tunes = response.get('results', [])
    total = response.get('total_records', 0)
    
    print(f"🤖 Fine-tuned models (tunes): {total}")
    
    if total == 0:
        print("   ✓ This is expected for a fresh deployment!")
        print("   ℹ️  We'll upload model checkpoints in Lab 3")
    else:
        print("   Found existing tunes:")
        for tune in tunes[:5]:  # Show first 5
            print(f"   - {tune.get('name', 'Unknown')}")
except Exception as e:
    print(f"❌ Error listing tunes: {e}")

In [ ]:

Copied!





# List inference requests
try:
    response = client.list_inferences()
    print("API Response:")
    print(response)
    print()

    # Extract results from paginated response
    inferences = response.get('results', [])
    total = response.get('total_records', 0)

    print(f"🔍 Inference requests: {total}")
    
    if total == 0:
        print("   ✓ This is expected for a fresh deployment!")
        print("   ℹ️  We'll run inferences in Lab 2")
    else:
        print("   Found existing inference requests:")
        for inference in inferences[:5]:  # Show first 5
            print(f"   - {inference.get('description', 'Unknown')}: {inference.get('status', 'No status')}")
except Exception as e:
    print(f"❌ Error listing inferences: {e}")
# List inference requests
try:
    response = client.list_inferences()
    print("API Response:")
    print(response)
    print()

    # Extract results from paginated response
    inferences = response.get('results', [])
    total = response.get('total_records', 0)

    print(f"🔍 Inference requests: {total}")
    
    if total == 0:
        print("   ✓ This is expected for a fresh deployment!")
        print("   ℹ️  We'll run inferences in Lab 2")
    else:
        print("   Found existing inference requests:")
        for inference in inferences[:5]:  # Show first 5
            print(f"   - {inference.get('description', 'Unknown')}: {inference.get('status', 'No status')}")
except Exception as e:
    print(f"❌ Error listing inferences: {e}")

Part 7: Understanding the API¶

SDK vs Direct API Calls¶

The SDK is a wrapper around the REST API. Let's see how they relate:

In [ ]:

Copied!





import requests
import json

# Get your configuration
with open('.geostudio_config_file', 'r') as f:
    config = dict(line.strip().split('=', 1) for line in f if '=' in line)

api_key = config['GEOSTUDIO_API_KEY']
base_url = config['BASE_STUDIO_UI_URL']

# Example: List datasets using direct API call
headers = {
    'X-API-Key': f'{api_key}',
    'Content-Type': 'application/json'
}

# This is what the SDK does internally
response = requests.get(
    f"{base_url}/studio-gateway/v2/datasets",
    headers=headers,
    verify=False  # Only for local development!
)

print(f"API Response Status: {response.status_code}")

# Check if response is successful and contains JSON
if response.status_code == 200:
    try:
        data = response.json()
        print(f"Response: {json.dumps(data, indent=2)[:500]}...")
    except json.JSONDecodeError:
        print(f"Response (text): {response.text[:500]}...")
else:
    print(f"Error: {response.text}")

print("\n💡 The SDK simplifies this to: client.list_datasets()")
import requests
import json

# Get your configuration
with open('.geostudio_config_file', 'r') as f:
    config = dict(line.strip().split('=', 1) for line in f if '=' in line)

api_key = config['GEOSTUDIO_API_KEY']
base_url = config['BASE_STUDIO_UI_URL']

# Example: List datasets using direct API call
headers = {
    'X-API-Key': f'{api_key}',
    'Content-Type': 'application/json'
}

# This is what the SDK does internally
response = requests.get(
    f"{base_url}/studio-gateway/v2/datasets",
    headers=headers,
    verify=False  # Only for local development!
)

print(f"API Response Status: {response.status_code}")

# Check if response is successful and contains JSON
if response.status_code == 200:
    try:
        data = response.json()
        print(f"Response: {json.dumps(data, indent=2)[:500]}...")
    except json.JSONDecodeError:
        print(f"Response (text): {response.text[:500]}...")
else:
    print(f"Error: {response.text}")

print("\n💡 The SDK simplifies this to: client.list_datasets()")

Part 8: SDK Helper Functions¶

The SDK provides many helper functions to make your life easier:

In [ ]:

Copied!





# Get client information
print("📋 Client Information:")
print(f"   Client initialized: ✓")
print(f"   API Version: v1")

# Available client methods
print("\n🔧 Available SDK Methods:")
methods = [m for m in dir(client) if not m.startswith('_') and callable(getattr(client, m))]
for method in sorted(methods)[:100]:  # Show first 100
    print(f"   - client.{method}()")
# Get client information
print("📋 Client Information:")
print(f"   Client initialized: ✓")
print(f"   API Version: v1")

# Available client methods
print("\n🔧 Available SDK Methods:")
methods = [m for m in dir(client) if not m.startswith('_') and callable(getattr(client, m))]
for method in sorted(methods)[:100]:  # Show first 100
    print(f"   - client.{method}()")

Part 9: Understanding the Workflow¶

Typical Geospatial Studio Workflow¶

1. 📊 Onboard Datasets
   ↓
2. 🎯 Select Base Model
   ↓
3. ⚙️  Fine-tune Model (Optional)
   ↓
4. 🚀 Run Inference
   ↓
5. 📈 Visualize Results
   ↓
6. 💾 Export/Share

What We'll Do in Upcoming Labs¶

Lab 2: Onboard pre-computed examples and datasets
Lab 3: Run inference with existing models
Lab 4: Complete end-to-end workflow (fine-tuning + inference)

Key Concepts to Remember¶

Datasets: Geospatial data (satellite imagery, labels, etc.)
Models: Pre-trained or fine-tuned AI models
Tasks: Types of ML tasks (segmentation, regression, etc.)
Inference: Running a model on new data
Fine-tuning: Adapting a model to your specific use case

Part 10: Troubleshooting Tips¶

Common Issues and Solutions¶

1. Connection Errors¶

# Check if Studio is accessible
import requests
try:
    response = requests.get(f"{base_url}/health", verify=False, timeout=5)
    print(f"✓ Studio is accessible: {response.status_code}")
except Exception as e:
    print(f"✗ Cannot reach Studio: {e}")
    print("  Check: Is Studio running? Is the URL correct?")

2. Authentication Errors¶

Verify your API key is correct
Check if the key has expired
Ensure you haven't exceeded the 2-key limit

3. Empty Results¶

This is normal for a fresh deployment!
Continue to Lab 2 to populate your Studio

Getting Help¶

Documentation: https://terrastackai.github.io/geospatial-studio/
SDK Docs: https://terrastackai.github.io/geospatial-studio-toolkit/
GitHub Issues: Report bugs and request features
Community: Join discussions and ask questions

Summary¶

What You Learned¶

✅ Studio Architecture: Understanding the components and how they work together

✅ UI Navigation: Exploring the Studio interface and generating API keys

✅ SDK Setup: Installing and configuring the Python SDK

✅ First API Calls: Connecting to Studio and checking platform status

✅ Three Interaction Methods: UI, API, and SDK - when to use each

Next Steps¶

Now that you're connected to Studio, you're ready to:

Lab 2: Onboard pre-computed examples and datasets
Lab 3: Run inference with existing models
Lab 4: Complete end-to-end burn scars workflow

Key Takeaways¶

🎯 Fresh deployment is normal: Empty catalogs are expected
🔑 API keys are essential: Keep them secure and don't commit them
🐍 SDK simplifies API: Use it for Python workflows
🖥️ UI for exploration: Great for visual feedback and learning
🔌 API for automation: Perfect for CI/CD and scripts

Ready for Lab 2? Let's start populating your Studio with data! 🚀