265 lines
8.5 KiB
Markdown
265 lines
8.5 KiB
Markdown
# EasyBallistics JSON Configuration Guide for Researchers
|
||
|
||
## Overview
|
||
|
||
This guide is designed for researchers, engineers, and scientists who need to configure ballistic simulation parameters without requiring knowledge of game development or Unreal Engine. The configuration files use self-documenting JSON format with embedded explanations.
|
||
|
||
## Getting Started
|
||
|
||
### Understanding the JSON Structure
|
||
|
||
Each configuration file follows this pattern:
|
||
```json
|
||
{
|
||
"ParameterName": {
|
||
"_description": "What this parameter does",
|
||
"_unit": "Units of measurement",
|
||
"_typical_values": "Expected ranges",
|
||
"_examples": "Real-world examples",
|
||
"value": actual_numeric_value
|
||
}
|
||
}
|
||
```
|
||
|
||
**Important**: The underscore-prefixed fields (`_description`, `_unit`, etc.) are documentation only. The `value` field contains the actual parameter that affects the simulation.
|
||
|
||
### File Types
|
||
|
||
1. **Bullet Properties** (`Sample_BulletProperties.json`) - Physical and ballistic characteristics of projectiles
|
||
2. **Material Response** (`Sample_MaterialResponse.json`) - How materials respond to ballistic impact
|
||
|
||
## Bullet Properties Configuration
|
||
|
||
### Essential Parameters
|
||
|
||
#### Mass and Dimensions
|
||
- **GrainWeight**: Projectile mass in grains (1 grain = 0.0647989 grams)
|
||
- Small caliber: 20-80 grains
|
||
- Medium caliber: 80-200 grains
|
||
- Large caliber: 200-750+ grains
|
||
|
||
- **DiameterInches**: Bullet diameter in inches
|
||
- Common values: 0.224" (5.56mm), 0.308" (7.62mm), 0.452" (45 ACP)
|
||
|
||
- **LengthInches**: Overall bullet length
|
||
- Typically 0.4-2.0 inches depending on caliber
|
||
|
||
#### Ballistic Coefficients
|
||
Choose **either** G1 or G7 model (set UseG7Model accordingly):
|
||
|
||
- **G1 Model**: Traditional standard, good for round-nose bullets
|
||
- Poor: 0.15-0.25
|
||
- Average: 0.25-0.45
|
||
- Excellent: 0.65+
|
||
|
||
- **G7 Model**: Better for modern pointed bullets
|
||
- Typically 0.5-0.7× the G1 value
|
||
- More accurate for boat-tail designs
|
||
|
||
#### Material Properties
|
||
- **BulletHardness**: Brinell Hardness Number
|
||
- Lead: 5-15 BHN
|
||
- Copper jacket: 15-25 BHN
|
||
- Steel core: 150-600 BHN
|
||
|
||
- **PenetrationEnergyThreshold**: Minimum energy for penetration (ft-lbs)
|
||
- Varies by intended use: 10-500+ ft-lbs
|
||
|
||
### Research Applications
|
||
|
||
#### Ballistics Research
|
||
For academic ballistics research, focus on:
|
||
- Accurate ballistic coefficients from wind tunnel data
|
||
- Precise mass and dimensional measurements
|
||
- Material hardness from standardized testing
|
||
|
||
#### Terminal Ballistics Studies
|
||
For penetration and wound ballistics:
|
||
- Expansion characteristics (velocity thresholds, max expansion)
|
||
- Energy transfer parameters
|
||
- Material-specific hardness values
|
||
|
||
#### Forensic Applications
|
||
For bullet identification and trajectory analysis:
|
||
- Precise dimensional measurements
|
||
- Material composition data
|
||
- Manufacturer-specific variations
|
||
|
||
## Material Response Configuration
|
||
|
||
### Penetration Mechanics
|
||
|
||
#### Basic Penetration
|
||
- **PenetrationDepthMultiplier**: Scaling factor (0.1-10.0)
|
||
- Use 1.0 as baseline, adjust based on experimental data
|
||
- Values <1.0 for harder materials, >1.0 for softer
|
||
|
||
- **PenetrationNormalization**: Angle dependency (degrees)
|
||
- 0-15°: Soft materials (wood, plastic)
|
||
- 15-30°: Medium materials (aluminum, mild steel)
|
||
- 30-60°: Hard materials (armor steel, ceramics)
|
||
|
||
#### Advanced Penetration Modeling
|
||
When **UseMathematicalProperties** is enabled:
|
||
|
||
- **DensityGPerCm3**: Material density from engineering handbooks
|
||
- **TensileStrengthMPa**: Ultimate tensile strength from material testing
|
||
- **YieldStrengthMPa**: Yield strength (typically 50-80% of tensile strength)
|
||
- **BallisticLimitVelocity**: V50 velocity from ballistic testing
|
||
|
||
### Ricochet Behavior
|
||
|
||
#### Key Parameters
|
||
- **RicochetProbabilityMultiplier**: Likelihood scaling (0.0-5.0)
|
||
- 0.0: No ricochets (soft materials)
|
||
- 1.0: Normal probability
|
||
- 2.0+: High ricochet materials (hardened steel, ice)
|
||
|
||
- **RicochetRestitution**: Energy retention (0.0-1.0)
|
||
- Soft materials: 0.1-0.3
|
||
- Hard materials: 0.7-0.9
|
||
|
||
### Spalling and Fragmentation
|
||
|
||
#### When to Enable Spalling
|
||
Spalling is relevant for:
|
||
- Brittle materials (concrete, ceramics, glass)
|
||
- High-energy impacts (>2000 fps)
|
||
- Research into secondary fragmentation effects
|
||
|
||
#### Critical Parameters
|
||
- **SpallVelocityThreshold**: Minimum impact velocity (cm/s)
|
||
- Glass: 15,000-30,000 cm/s
|
||
- Concrete: 30,000-60,000 cm/s
|
||
- Steel: 60,000+ cm/s
|
||
|
||
- **SpallFragmentCount**: Number of fragments (1-20)
|
||
- Balance realism vs. computational cost
|
||
- Typical: 3-8 fragments for most materials
|
||
|
||
## Data Sources and Validation
|
||
|
||
### Recommended References
|
||
|
||
#### Bullet Properties
|
||
1. **Manufacturer Data**: Official ballistic coefficients and specifications
|
||
2. **Ballistic Tables**: Sierra, Hornady, Nosler reloading manuals
|
||
3. **Military Standards**: NATO STANAG documents for military ammunition
|
||
4. **SAAMI Standards**: Sporting Arms and Ammunition Manufacturers' Institute
|
||
|
||
#### Material Properties
|
||
1. **ASTM Standards**: Material testing standards (E8, E10, etc.)
|
||
2. **Engineering Handbooks**: ASM Metals Handbook, Machinery's Handbook
|
||
3. **Research Literature**: Journal of Applied Physics, International Journal of Impact Engineering
|
||
4. **Government Databases**: NIST materials database, military research reports
|
||
|
||
### Experimental Validation
|
||
|
||
#### Ballistic Testing
|
||
- Use chronographs for velocity measurements
|
||
- Ballistic gelatin for terminal performance
|
||
- Steel plate testing for penetration limits
|
||
- High-speed photography for fragment analysis
|
||
|
||
#### Material Testing
|
||
- Tensile testing per ASTM E8
|
||
- Hardness testing per ASTM E10
|
||
- Impact testing per ASTM E23
|
||
- Ballistic limit testing per MIL-STD protocols
|
||
|
||
## Common Material Examples
|
||
|
||
### Metals
|
||
```json
|
||
// Mild Steel (A36)
|
||
"DensityGPerCm3": 7.85,
|
||
"MaterialHardness": 150.0,
|
||
"TensileStrengthMPa": 400.0,
|
||
"YieldStrengthMPa": 250.0
|
||
|
||
// Aluminum 6061-T6
|
||
"DensityGPerCm3": 2.70,
|
||
"MaterialHardness": 95.0,
|
||
"TensileStrengthMPa": 310.0,
|
||
"YieldStrengthMPa": 276.0
|
||
|
||
// Hardened Steel (Armor)
|
||
"DensityGPerCm3": 7.85,
|
||
"MaterialHardness": 500.0,
|
||
"TensileStrengthMPa": 1200.0,
|
||
"YieldStrengthMPa": 1000.0
|
||
```
|
||
|
||
### Ceramics and Composites
|
||
```json
|
||
// Alumina Ceramic
|
||
"DensityGPerCm3": 3.95,
|
||
"MaterialHardness": 1500.0,
|
||
"TensileStrengthMPa": 300.0,
|
||
"YieldStrengthMPa": 300.0,
|
||
"EnableSpalling": true
|
||
|
||
// Kevlar Composite
|
||
"DensityGPerCm3": 1.44,
|
||
"MaterialHardness": 50.0,
|
||
"TensileStrengthMPa": 3500.0,
|
||
"YieldStrengthMPa": 3500.0,
|
||
"NeverRicochet": true
|
||
```
|
||
|
||
## Quality Assurance
|
||
|
||
### Parameter Validation
|
||
1. **Physical Consistency**: Ensure yield strength ≤ tensile strength
|
||
2. **Unit Consistency**: Verify all units match the documentation
|
||
3. **Range Checking**: Compare values against published material databases
|
||
4. **Cross-Reference**: Validate against multiple independent sources
|
||
|
||
### Simulation Validation
|
||
1. **Known Results**: Test against published ballistic data
|
||
2. **Sensitivity Analysis**: Vary parameters to understand system response
|
||
3. **Comparative Testing**: Compare results between different bullet/material combinations
|
||
4. **Literature Comparison**: Validate results against peer-reviewed research
|
||
|
||
## Troubleshooting
|
||
|
||
### Common Issues
|
||
1. **Unrealistic Penetration**: Check density and hardness values
|
||
2. **No Expansion**: Verify expansion velocity threshold vs. impact velocity
|
||
3. **Excessive Ricochets**: Reduce ricochet probability multiplier
|
||
4. **Performance Issues**: Reduce spalling fragment count and density
|
||
|
||
### Best Practices
|
||
1. **Start Simple**: Begin with basic parameters, add complexity gradually
|
||
2. **Document Sources**: Record where each value came from for traceability
|
||
3. **Version Control**: Keep track of parameter changes and their effects
|
||
4. **Peer Review**: Have other researchers validate your parameter choices
|
||
|
||
## Advanced Research Applications
|
||
|
||
### Multi-Material Studies
|
||
For composite armor or layered materials:
|
||
- Configure each layer separately
|
||
- Account for interface effects
|
||
- Consider cumulative energy absorption
|
||
|
||
### Dynamic Effects
|
||
For high strain rate phenomena:
|
||
- Use dynamic strength values (typically 1.5-3× static)
|
||
- Account for temperature effects
|
||
- Consider strain rate sensitivity
|
||
|
||
### Statistical Analysis
|
||
For probabilistic studies:
|
||
- Use parameter ranges rather than single values
|
||
- Apply Monte Carlo methods
|
||
- Document uncertainty and sensitivity
|
||
|
||
## Contact and Support
|
||
|
||
For research collaborations or technical questions:
|
||
- Review the complete API documentation
|
||
- Consult the troubleshooting guide
|
||
- Consider experimental validation of critical parameters
|
||
|
||
This configuration system is designed to support serious ballistics research while maintaining computational efficiency. The self-documenting JSON format ensures that parameter choices are traceable and scientifically justified. |