Initial
This commit is contained in:
Jason
@@ -0,0 +1,221 @@
|
||||
# Bitwise Helper Files - Usage Guide
|
||||
|
||||
## 📁 Generated Files
|
||||
|
||||
1. **`data/product_bitwise.csv`** - CSV format with bit values for each product
|
||||
2. **`data/product_bitwise.json`** - JSON format with bit values for each product
|
||||
3. **`data/bitwise_legend.json`** - Complete bit mapping documentation
|
||||
|
||||
## 🔢 Bit System Overview
|
||||
|
||||
Each product gets a single integer value that encodes multiple attributes using bitwise flags.
|
||||
|
||||
### Bit Positions (0-11): Base Attributes, Materials, Colors
|
||||
|
||||
| Bit | Value | Attribute |
|
||||
|-----|-------|-----------|
|
||||
| 0 | 1 | Door |
|
||||
| 1 | 2 | Window |
|
||||
| 2 | 4 | Is Accessory |
|
||||
| 3 | 8 | Specific Item Link |
|
||||
| 4 | 16 | Aluminum Material |
|
||||
| 5 | 32 | Vinyl Material |
|
||||
| 6 | 64 | Black Color |
|
||||
| 7 | 128 | White Color |
|
||||
| 8 | 256 | Bronze Color |
|
||||
| 9 | 512 | Tan Color |
|
||||
| 10 | 1024 | Mill Color |
|
||||
| 11 | 2048 | Sandstone Color |
|
||||
|
||||
### Bit Positions (12+): Sub-types
|
||||
|
||||
| Bit | Value | Sub-type |
|
||||
|-----|-------|----------|
|
||||
| 12 | 4096 | Patio Door |
|
||||
| 13 | 8192 | Primary Window |
|
||||
| 14 | 16384 | Storm Door |
|
||||
| 15 | 32768 | Storm Window |
|
||||
|
||||
## 💡 Usage Examples
|
||||
|
||||
### Example 1: Storm Door Insert (BGIST)
|
||||
```
|
||||
Product Code: BGIST
|
||||
Description: INSERTS FOR STORM DOORS
|
||||
Bit Value: 17553
|
||||
Binary: 0100010010010001
|
||||
|
||||
Decoded:
|
||||
✓ Door (bit 0 = 1)
|
||||
✗ Window (bit 1 = 0)
|
||||
✗ Accessory (bit 2 = 0)
|
||||
✗ Specific Item (bit 3 = 0)
|
||||
✓ Aluminum (bit 4 = 1)
|
||||
✗ Vinyl (bit 5 = 0)
|
||||
✓ Black (bit 6 = 1)
|
||||
✓ White (bit 7 = 1)
|
||||
✓ Bronze (bit 8 = 1)
|
||||
✗ Tan (bit 9 = 0)
|
||||
✓ Mill (bit 10 = 1)
|
||||
✓ Sandstone (bit 11 = 1)
|
||||
✗ Patio Door (bit 12 = 0)
|
||||
✗ Primary Window (bit 13 = 0)
|
||||
✓ Storm Door (bit 14 = 1)
|
||||
✗ Storm Window (bit 15 = 0)
|
||||
```
|
||||
|
||||
### Example 2: Check Attributes in Code
|
||||
|
||||
#### Python
|
||||
```python
|
||||
import json
|
||||
|
||||
# Load helper file
|
||||
with open('data/product_bitwise.json') as f:
|
||||
products = json.load(f)
|
||||
|
||||
# Get a product
|
||||
product = next(p for p in products if p['PROD_CODE'] == 'BGIST')
|
||||
bit_value = product['BIT_VALUE']
|
||||
|
||||
# Check individual flags
|
||||
is_door = bool(bit_value & 1)
|
||||
is_aluminum = bool(bit_value & 16)
|
||||
is_white = bool(bit_value & 128)
|
||||
is_storm_door = bool(bit_value & 16384)
|
||||
|
||||
print(f"BGIST is door: {is_door}")
|
||||
print(f"BGIST is aluminum: {is_aluminum}")
|
||||
print(f"BGIST is white: {is_white}")
|
||||
print(f"BGIST is storm door subtype: {is_storm_door}")
|
||||
|
||||
# Filter products by multiple criteria
|
||||
# Example: Find all aluminum doors with white color
|
||||
aluminum_white_doors = [
|
||||
p for p in products
|
||||
if (p['BIT_VALUE'] & 1) and # Is a door
|
||||
(p['BIT_VALUE'] & 16) and # Has aluminum
|
||||
(p['BIT_VALUE'] & 128) and # Has white
|
||||
not p['DISCONTINUED'] # Not discontinued
|
||||
]
|
||||
|
||||
print(f"Found {len(aluminum_white_doors)} aluminum white doors")
|
||||
```
|
||||
|
||||
#### JavaScript
|
||||
```javascript
|
||||
// Load the JSON file
|
||||
fetch('data/product_bitwise.json')
|
||||
.then(response => response.json())
|
||||
.then(products => {
|
||||
// Check individual flags
|
||||
const product = products.find(p => p.PROD_CODE === 'BGIST');
|
||||
const bitValue = product.BIT_VALUE;
|
||||
|
||||
const isDoor = !!(bitValue & 1);
|
||||
const isAluminum = !!(bitValue & 16);
|
||||
const isWhite = !!(bitValue & 128);
|
||||
const isStormDoor = !!(bitValue & 16384);
|
||||
|
||||
console.log(`BGIST is door: ${isDoor}`);
|
||||
console.log(`BGIST is aluminum: ${isAluminum}`);
|
||||
console.log(`BGIST is white: ${isWhite}`);
|
||||
console.log(`BGIST is storm door: ${isStormDoor}`);
|
||||
|
||||
// Filter products
|
||||
const aluminumWhiteDoors = products.filter(p =>
|
||||
(p.BIT_VALUE & 1) && // Is a door
|
||||
(p.BIT_VALUE & 16) && // Has aluminum
|
||||
(p.BIT_VALUE & 128) && // Has white
|
||||
!p.DISCONTINUED // Not discontinued
|
||||
);
|
||||
|
||||
console.log(`Found ${aluminumWhiteDoors.length} aluminum white doors`);
|
||||
});
|
||||
```
|
||||
|
||||
## 🎯 Benefits of Bitwise Classification
|
||||
|
||||
### 1. **Multi-Group Assignment**
|
||||
Products can belong to multiple categories simultaneously:
|
||||
- A product can be both Door AND Window (rare but possible)
|
||||
- A product can have multiple materials (Aluminum AND Vinyl)
|
||||
- A product can have multiple colors
|
||||
|
||||
### 2. **Fast Filtering**
|
||||
Bitwise operations are extremely fast:
|
||||
```python
|
||||
# Instead of:
|
||||
if product.baseType == 'Door' and 'Aluminum' in product.materials and 'White' in product.colors:
|
||||
|
||||
# Use:
|
||||
if (bit_value & 1) and (bit_value & 16) and (bit_value & 128):
|
||||
```
|
||||
|
||||
### 3. **Compact Storage**
|
||||
One integer stores multiple attributes:
|
||||
- Single integer vs. multiple boolean fields
|
||||
- Easy to index and search in databases
|
||||
- Efficient for large datasets
|
||||
|
||||
### 4. **Easy Matching**
|
||||
Perfect for accessory compatibility:
|
||||
```python
|
||||
# Check if accessory matches product materials
|
||||
accessory_materials = 48 # Aluminum (16) + Vinyl (32)
|
||||
product_materials = 16 # Aluminum only
|
||||
|
||||
# Check if they share any materials
|
||||
if accessory_materials & product_materials:
|
||||
print("Compatible!") # True because both have Aluminum
|
||||
```
|
||||
|
||||
## 🔄 Integration with Navigation System
|
||||
|
||||
Use bitwise values to:
|
||||
1. Dynamically generate navigation options
|
||||
2. Filter products in real-time based on user selections
|
||||
3. Match accessories to products efficiently
|
||||
4. Handle complex "OR" queries (multiple categories)
|
||||
|
||||
### Example: Dynamic Material Question
|
||||
```python
|
||||
# Get all products for "Storm Door" subtype
|
||||
storm_door_products = [p for p in products if p['BIT_VALUE'] & 16384]
|
||||
|
||||
# Check materials
|
||||
has_aluminum = any(p['BIT_VALUE'] & 16 for p in storm_door_products)
|
||||
has_vinyl = any(p['BIT_VALUE'] & 32 for p in storm_door_products)
|
||||
|
||||
# Show material question only if multiple materials exist
|
||||
if has_aluminum and has_vinyl:
|
||||
show_material_question()
|
||||
else:
|
||||
skip_to_next_question()
|
||||
```
|
||||
|
||||
## 📝 Maintenance
|
||||
|
||||
### Regenerating Helper Files
|
||||
When products.csv changes:
|
||||
```bash
|
||||
python generate_bitwise_helper.py
|
||||
```
|
||||
|
||||
### Adding New Attributes
|
||||
To add new bit flags, edit `generate_bitwise_helper.py`:
|
||||
1. Add to `BIT_DEFINITIONS` dictionary
|
||||
2. Update `calculate_bit_value()` function
|
||||
3. Regenerate files
|
||||
|
||||
### Adding New Sub-types
|
||||
Sub-types are automatically detected! Just add them to columns H or I in the CSV, then regenerate.
|
||||
|
||||
## 🚀 Performance Notes
|
||||
|
||||
- Bitwise AND (`&`) - Check if flag is set: `bit_value & 16`
|
||||
- Bitwise OR (`|`) - Combine flags: `16 | 128` = Aluminum + White
|
||||
- Bitwise NOT (`~`) - Invert flags (advanced)
|
||||
- Bitwise XOR (`^`) - Toggle flags (advanced)
|
||||
|
||||
All bitwise operations are O(1) - constant time!
|
||||
Reference in New Issue
Block a user