Skip to content

Latest commit

 

History

History
327 lines (291 loc) · 11.5 KB

quickstart.md

File metadata and controls

327 lines (291 loc) · 11.5 KB
layout title
default
Quick Start Guide
Get started with OpenPIV in 5 minutes! This guide will help you install and run your first PIV analysis.
1

Install OpenPIV

Choose your preferred installation method:

  <!-- Tabs for installation -->
  <ul class="nav nav-tabs" id="installTabs" role="tablist">
    <li class="nav-item" role="presentation">
      <button class="nav-link active" id="pip-tab" data-bs-toggle="tab" data-bs-target="#pip-panel" type="button" role="tab">
        <i class="bi bi-box"></i> pip
      </button>
    </li>
    <li class="nav-item" role="presentation">
      <button class="nav-link" id="conda-tab" data-bs-toggle="tab" data-bs-target="#conda-panel" type="button" role="tab">
        <i class="bi bi-cloud"></i> conda
      </button>
    </li>
  </ul>
  
  <div class="tab-content mt-3" id="installTabsContent">
    <div class="tab-pane fade show active" id="pip-panel" role="tabpanel">
      <div class="code-block">
        <button class="copy-btn" data-clipboard-text="pip install openpiv">
          <i class="bi bi-clipboard"></i> Copy
        </button>
        <pre><code>pip install openpiv</code></pre>
      </div>
      <p class="mt-2 text-muted small">Requires Python 3.8 or higher</p>
    </div>
    <div class="tab-pane fade" id="conda-panel" role="tabpanel">
      <div class="code-block">
        <button class="copy-btn" data-clipboard-text="conda install -c conda-forge openpiv">
          <i class="bi bi-clipboard"></i> Copy
        </button>
        <pre><code>conda install -c conda-forge openpiv</code></pre>
      </div>
      <p class="mt-2 text-muted small">Recommended for scientific Python users</p>
    </div>
  </div>
</div>
2

Get Sample PIV Images

Download example images or use your own PIV image pairs:

  <div class="code-block">
    <button class="copy-btn" data-clipboard-text="from openpiv import tools

frame_a, frame_b = tools.imread('exp1_001_a.bmp'), tools.imread('exp1_001_b.bmp')"> Copy 

from openpiv import tools
frame_a, frame_b = tools.imread('exp1_001_a.bmp'), tools.imread('exp1_001_b.bmp')

  <div class="alert alert-light mt-3">
    <i class="bi bi-download"></i> <strong>Sample Data:</strong> You can download test images from the <a href="https://github.com/OpenPIV/openpiv-python/tree/master/openpiv/data" target="_blank">OpenPIV GitHub repository</a>
  </div>
</div>
3

Run Your First Analysis

Use this simple script to perform PIV analysis:

  <div class="code-block">
    <button class="copy-btn" data-clipboard-text="import openpiv.tools

import openpiv.process import openpiv.scaling

Load images

frame_a = openpiv.tools.imread('exp1_001_a.bmp') frame_b = openpiv.tools.imread('exp1_001_b.bmp')

Run PIV analysis

u, v, sig2noise = openpiv.process.extended_search_area_piv( frame_a, frame_b, window_size=32, overlap=16, dt=0.02, search_area_size=64 )

Scale to physical units (example: 1 pixel = 0.1 mm, dt = 0.02 s)

x, y, u, v = openpiv.scaling.uniform( u, v, scaling_factor=0.1/0.02 # 5 mm/s per pixel/frame )

Save results

openpiv.tools.save(x, y, u, v, 'output.txt')

print('PIV analysis complete! Results saved to output.txt')"> Copy 

import openpiv.tools
import openpiv.process
import openpiv.scaling


Load images


frame_a = openpiv.tools.imread('exp1_001_a.bmp')
frame_b = openpiv.tools.imread('exp1_001_b.bmp')


Run PIV analysis


u, v, sig2noise = openpiv.process.extended_search_area_piv(
frame_a, frame_b,
window_size=32,
overlap=16,
dt=0.02,
search_area_size=64
)


Scale to physical units (example: 1 pixel = 0.1 mm, dt = 0.02 s)


x, y, u, v = openpiv.scaling.uniform(
u, v,
scaling_factor=0.1/0.02  # 5 mm/s per pixel/frame
)


Save results


openpiv.tools.save(x, y, u, v, 'output.txt')


print('PIV analysis complete! Results saved to output.txt')

4

Visualize Your Results

Create beautiful velocity field plots:

  <div class="code-block">
    <button class="copy-btn" data-clipboard-text="import matplotlib.pyplot as plt

import openpiv.tools

Load results

x, y, u, v = openpiv.tools.load('output.txt')

Create quiver plot

fig, ax = plt.subplots(figsize=(10, 8)) ax.quiver(x, y, u, v, scale=50) ax.set_xlabel('X [mm]') ax.set_ylabel('Y [mm]') ax.set_title('PIV Velocity Field') plt.savefig('velocity_field.png', dpi=150) plt.show()"> Copy 

import matplotlib.pyplot as plt
import openpiv.tools


Load results


x, y, u, v = openpiv.tools.load('output.txt')


Create quiver plot


fig, ax = plt.subplots(figsize=(10, 8))
ax.quiver(x, y, u, v, scale=50)
ax.set_xlabel('X [mm]')
ax.set_ylabel('Y [mm]')
ax.set_title('PIV Velocity Field')
plt.savefig('velocity_field.png', dpi=150)
plt.show()

Try OpenPIV Online

No installation required! Test OpenPIV in your browser.

      <div class="row mt-4">
        <div class="col-md-6 mb-3">
          <a href="https://colab.research.google.com/github/OpenPIV/openpiv-python/blob/master/openpiv/examples/notebooks/tutorial.ipynb" 
             class="btn btn-primary btn-lg" target="_blank">
            <i class="bi bi-google"></i> Open in Google Colab
          </a>
        </div>
        <div class="col-md-6 mb-3">
          <a href="https://molab.marimo.io/notebooks/nb_ZpcirbacVvBP3ZgbdCgKhM" 
             class="btn btn-outline-primary btn-lg" target="_blank">
            <i class="bi bi-book"></i> Try Marimo Notebook
          </a>
        </div>
      </div>
    </div>
  </div>
</div>

What's Next?

<div class="row">
  <div class="col-md-4 mb-4">
    <div class="next-step-card">
      <i class="bi bi-book"></i>
      <h4>Learn More</h4>
      <p>Explore detailed tutorials and documentation</p>
      <a href="{{ site.baseurl }}/gettingstarted.html" class="btn btn-outline-primary">
        View Tutorials
      </a>
    </div>
  </div>
  
  <div class="col-md-4 mb-4">
    <div class="next-step-card">
      <i class="bi bi-question-circle"></i>
      <h4>Get Help</h4>
      <p>Browse FAQ and join the community forum</p>
      <a href="{{ site.baseurl }}/faq.html" class="btn btn-outline-primary">
        Read FAQ
      </a>
    </div>
  </div>
  
  <div class="col-md-4 mb-4">
    <div class="next-step-card">
      <i class="bi bi-code-slash"></i>
      <h4>Advanced Features</h4>
      <p>GPU acceleration, validation, filtering, and more</p>
      <a href="https://openpiv.readthedocs.io" class="btn btn-outline-primary" target="_blank">
        API Documentation
      </a>
    </div>
  </div>
</div>

Troubleshooting

      <div class="accordion mt-3" id="troubleshootingAccordion">
        <div class="accordion-item">
          <h2 class="accordion-header">
            <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#trouble1">
              Installation fails with permission error
            </button>
          </h2>
          <div id="trouble1" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion">
            <div class="accordion-body">
              Try installing in user mode: <code>pip install --user openpiv</code>
              <br>Or use a virtual environment: <code>python -m venv myenv</code>
            </div>
          </div>
        </div>
        
        <div class="accordion-item">
          <h2 class="accordion-header">
            <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#trouble2">
              ImportError: No module named 'openpiv'
            </button>
          </h2>
          <div id="trouble2" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion">
            <div class="accordion-body">
              Make sure you're using the correct Python environment. Check with: <code>python -m pip show openpiv</code>
            </div>
          </div>
        </div>
        
        <div class="accordion-item">
          <h2 class="accordion-header">
            <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#trouble3">
              Poor PIV results or many spurious vectors
            </button>
          </h2>
          <div id="trouble3" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion">
            <div class="accordion-body">
              Try adjusting parameters:
              <ul>
                <li>Increase <code>window_size</code> for larger displacements</li>
                <li>Increase <code>search_area_size</code> if particles move far between frames</li>
                <li>Adjust <code>overlap</code> for better spatial resolution</li>
                <li>Check image quality and particle seeding density</li>
              </ul>
              See the <a href="{{ site.baseurl }}/faq.html">FAQ</a> for more parameter guidance.
            </div>
          </div>
        </div>
      </div>
      
      <div class="mt-4 text-center">
        <p><strong>Still need help?</strong></p>
        <a href="https://groups.google.com/forum/#!forum/openpiv-users" class="btn btn-primary" target="_blank">
          <i class="bi bi-people"></i> Ask on Forum
        </a>
        <a href="mailto:openpiv2008@gmail.com" class="btn btn-outline-primary">
          <i class="bi bi-envelope"></i> Email Us
        </a>
      </div>
    </div>
  </div>
</div>