Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
268 lines (208 loc) · 7.02 KB

GETTING_STARTED.md

File metadata and controls

268 lines (208 loc) · 7.02 KB

Getting Started with the DIGGS Hackathon

Prerequisites

Required Knowledge

  • Basic programming skills in any language
  • Understanding of XML/JSON data structures (helpful but not required)
  • Familiarity with geotechnical concepts (helpful but not required)

Recommended Tools

  • Code Editor: VS Code, PyCharm, or your preferred IDE
  • Version Control: Git
  • Database Browser: SQLite Browser or DBeaver
  • XML Editor: Any text editor with XML syntax highlighting

Setting Up Your Development Environment

Step 1: Clone the Repository

git clone https://github.com/[your-org]/DIggs_Hack-a-Thon_2025.git
cd DIggs_Hack-a-Thon_2025

Step 2: Choose Your Technology Stack

Python Setup

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r examples/python_starter/requirements.txt

JavaScript/Node.js Setup

# Navigate to JavaScript examples
cd examples/javascript_starter

# Install dependencies
npm install

Other Languages

Feel free to use any programming language! The DIGGS files are XML-based and can be parsed by any language with XML support.

Step 3: Explore the Data (Available January 5, 2026)

DIGGS XML Files

# Example: Reading a DIGGS file in Python
import xml.etree.ElementTree as ET

tree = ET.parse('data/sample_diggs_files/boring_log_example.xml')
root = tree.getroot()

# Explore the structure
for child in root:
    print(child.tag, child.attrib)

SQLite Database

-- Connect to the database
-- sqlite3 data/diggs_database.db

-- View available tables
.tables

-- Example query
SELECT * FROM borings LIMIT 5;

Understanding DIGGS Structure

Key DIGGS Elements

  1. Project Information

    • Project name, location, date
    • Client and contractor details
    • Coordinate reference systems

  2. Boring/Sampling Data

    • Boring locations and depths
    • Sampling methods
    • Field observations

  3. Laboratory Test Results

    • Soil classification
    • Strength parameters
    • Index properties

  4. In-Situ Test Data

    • SPT (Standard Penetration Test)
    • CPT (Cone Penetration Test)
    • Pressuremeter tests

DIGGS Namespace

<diggs:Diggs xmlns:diggs="http://diggsml.org/schemas/2.5" 
             xmlns:gml="http://www.opengis.net/gml/3.2">
    <!-- DIGGS content here -->
</diggs:Diggs>

Quick Start Examples

Example 1: Parse DIGGS File (Python)

from examples.python_starter import diggs_parser

# Load DIGGS file
diggs_data = diggs_parser.load_diggs_file('path/to/file.xml')

# Extract boring information
borings = diggs_parser.get_borings(diggs_data)
for boring in borings:
    print(f"Boring ID: {boring['id']}, Depth: {boring['depth']}")

Example 2: Query Database (SQL)

-- Find all borings deeper than 50 feet
SELECT boring_id, total_depth, location_x, location_y
FROM borings
WHERE total_depth > 50
ORDER BY total_depth DESC;

Example 3: Simple Visualization (JavaScript)

const { parseDiggsFile } = require('./examples/javascript_starter');

// Load and visualize data
parseDiggsFile('path/to/file.xml')
  .then(data => {
    // Create simple visualization
    console.log(`Found ${data.borings.length} borings`);
    // Add your visualization code here
  });

Development Workflow

1. Planning Phase

  • Review the challenge themes
  • Explore the sample data
  • Identify your target users
  • Sketch out your solution

2. Development Phase

1. Set up your project structure
2. Implement core functionality
3. Test with sample data
4. Add user interface (if applicable)
5. Optimize and refine
6. Document your code

3. Testing Phase

  • Test with different DIGGS files
  • Handle edge cases
  • Validate output accuracy
  • Performance testing with large files

4. Documentation Phase

  • Write clear README
  • Add code comments
  • Create user guide
  • Prepare demo materials

Common Tasks and Solutions

Reading DIGGS XML Files

Most languages have XML parsing libraries:

  • Python: xml.etree, lxml, xmltodict
  • JavaScript: xml2js, fast-xml-parser
  • Java: JAXB, DOM, SAX
  • C#: System.Xml, XDocument

Working with the SQLite Database

  • Python: sqlite3 (built-in), SQLAlchemy
  • JavaScript: better-sqlite3, node-sqlite3
  • Java: JDBC
  • C#: System.Data.SQLite

Creating Visualizations

  • Web-based: D3.js, Chart.js, Plotly.js, Three.js
  • Python: Matplotlib, Plotly, Bokeh
  • Desktop: Qt, Tkinter, WPF

Troubleshooting

Issue: XML Parsing Errors

Solution: Check for proper namespace handling and UTF-8 encoding

Issue: Large File Performance

Solution: Use streaming parsers (SAX) instead of loading entire file into memory

Issue: Database Connection Issues

Solution: Ensure SQLite drivers are installed and path is correct

Issue: Coordinate System Confusion

Solution: DIGGS uses various CRS; check the gml:srsName attribute

Useful Resources

DIGGS Documentation & Tools

Geotechnical References

  • ASTM Standards for soil testing
  • USCS Soil Classification System
  • Local building codes and standards

Development Tools

Getting Help

During the Hackathon

  1. Check the FAQ in CHALLENGE_BRIEF.md
  2. Review example code in /examples/
  3. Attend Weekly DIGGS Team Office Hours (one day per week)
  4. Collaborate with other participants

Technical Support

  • Weekly Office Hours: Direct access to DIGGS experts
  • GitHub Issues for code problems
  • Slack/Discord for quick questions
  • Mentor sessions for guidance

Next Steps

  1. ✅ Set up your development environment
  2. ✅ Run the example code
  3. ✅ Explore the data structure
  4. 🎯 Choose your challenge theme
  5. 🚀 Start building!

Pro Tips

  1. Start Small: Build a working prototype first, then add features
  2. Use Version Control: Commit your code frequently
  3. Test Early: Don't wait until the end to test with real data
  4. Document as You Go: Write comments while the code is fresh
  5. Ask for Feedback: Get input from mentors and peers
  6. Have Fun: This is a learning opportunity!

Ready to get started? The geotechnical data revolution begins with you! 🌍⚒️