BulletAnalyzr Quick Start Guide
What is BulletAnalyzr?
BulletAnalyzr is a forensic tool that uses 3D imaging and advanced algorithms to compare bullets and determine if they were fired from the same gun. It’s free, open-source, and currently in alpha testing (research and lab testing only - not yet validated for casework).
Key Features
- Interactive 3D visualization of bullet scans
- Automated crosscut and groove detection
- Manual refinement controls with intuitive sliders
- Comprehensive comparison reports
- Works with x3p format 3D scans
Installation (60-80 minutes total)
1. Install Required Software (20-30 minutes)
- Install R from https://cran.r-project.org/
- Install RStudio from https://posit.co/download/rstudio-desktop/
- Download BulletAnalyzr from https://github.com/CSAFE-ISU/bulletAnalyzr
- Click the green “Code” button then “Download ZIP”
- Unzip the downloaded file anywhere on your computer
2. Install R Packages (45-50 minutes)
- Open RStudio
- In the Console (after the
> symbol), paste and run:
# Install packages from CRAN
cran_packages <- c("bsicons", "bslib", "curl", "devtools", "dplyr", "DT",
"ggplot2", "pagedown", "randomForest", "rgl", "sessioninfo",
"shiny", "shinyBS", "shinycssloaders", "shinyjs")
for (pkg in cran_packages) {
install.packages(pkg)
}
# Install packages from GitHub
github_packages <- c("heike/bulletxtrctr", "heike/x3ptools")
for (pkg in github_packages) {
devtools::install_github(pkg)
}
Launch BulletAnalyzr
- Navigate to your unzipped
bulletAnalyzr-main folder
- Double-click
rstudio.Rproj to open the project in RStudio
- In RStudio’s Files tab, open the
app folder
- Click
server.R to open it
- Click Run App in the top-right of the editor
- Click Begin on the home screen
Basic Workflow (15-20 minutes with example data)
Step 1: Upload Bullets
- Click Browse and navigate to
bulletAnalyzr-main/examples/Hamby-44/Barrel 1/Bullet 1
- Select all 6
.x3p files (each is one land engraved area)
- Give the bullet a name (e.g., “Bullet 1”)
- Click Add Bullet to Comparison List
- Repeat for Bullet 2 (
bulletAnalyzr-main/examples/Hamby-44/Barrel 1/Bullet 2)
Step 2: Adjust Crosscut Locations
Crosscuts appear as light grey lines on the 3D bullet renderings.
- Select Bullet 1 from the drop-down
- Use sliders to adjust crosscut positions if needed
- Click Finalize Crosscut
- Repeat for Bullet 2
- Click Compare Bullets
Step 3: Adjust Groove Placements
Grooves need to be removed before analysis.
- Select Bullet 1 and Land 1 from the drop-downs
- Red vertical lines show groove locations on the crosscut profile plot
- Adjust sliders to keep as much land as possible while removing grooves
- Click Save Grooves
- Repeat for all lands on both bullets (12 total)
- Click Next Step
Step 4: Review Results
The report shows:
- Phase test score and probability of false identification (top)
- Bullet-to-bullet score matrix (0 = no similarity, 1 = perfect match)
- Land-to-land score matrix showing individual land comparisons
- Profile plots and signal plots for each land
- Detailed feature comparisons for top matches
Click Download Report to save a copy.
Important Usage Notes
⚠️ Not for casework: BulletAnalyzr is in alpha testing and has not been validated for use in casework or court testimony. Use only for:
- Research purposes
- Internal lab testing and evaluation
Citation
If you use BulletAnalyzr in research, please cite:
Eric Hare, Heike Hofmann, Alicia Carriquiry. “Algorithmic approaches to match degraded land impressions.” Law, Probability and Risk, Volume 16, Issue 4, December 2017, Pages 203-221. https://doi.org/10.1093/lpr/mgx018
Eric Hare, Heike Hofmann, and Alicia Carriquiry. “Automatic Matching of Bullet Land Impressions.” The Annals of Applied Statistics, Volume 11, Number 4, 2017, pp. 2332-56. http://www.jstor.org/stable/26362188
License
GNU GPL version 3
Support
For more detailed instructions, see the full user guide.