Application Domains
| Domain | Applications | Related Modules |
|---|---|---|
| Medical Imaging | Tissue complexity, heterogeneity analysis | Multifractal spectrum, fractal dimension |
| Materials Science | Surface morphology, porous structure | Fractal dimension, lacunarity |
| Financial Analysis | Price fluctuations, risk assessment | Series multifractal spectrum |
| Earth Sciences | Terrain analysis, vegetation distribution | Fractal dimension, lacunarity |
| Image Processing | Texture classification, image segmentation | All modules |
Installation
pip install FreeAeon-Fractal
Requirements:
- Python 3.6+
- OpenCV (cv2) support
For series analysis: pip install MFDFA
For GPU acceleration: pip install torch --index-url https://download.pytorch.org/whl/cu118
Feature Modules
| Module | Class | Features | Docs |
|---|---|---|---|
| Multifractal | CFAImageMFS | 2D image multifractal spectrum, alpha map | View |
| CFASeriesMFS | 1D series multifractal spectrum (MFDFA) | View | |
| Fractal Dimension | CFAImageFD | BC/DBC/SDBC methods, batch processing | View |
| Lacunarity | CFAImageLAC | Gliding/Non-overlapping, integral image speedup | View |
| Fourier Analysis | CFAImageFourier | Spectrum, custom mask filtering, reconstruction | View |
| Image Utils | CFAImage | Blocking, binarization, ROI by q | View |
| Visualization | CFAVisual | 1D/2D/3D point & image display | View |
| Sample Gen | CFASample | Cantor Set, Sierpinski, Barnsley Fern, Menger Sponge | View |
| GPU Accel | *GPU versions | 3–20× speedup for FD, MFS, LAC | View |
Quick Start
Multifractal Spectrum of an Image
import cv2, numpy as np
from FreeAeonFractal.FAImageMFS import CFAImageMFS
rgb_image = cv2.imread('./images/face.png')
gray_image = cv2.cvtColor(rgb_image, cv2.COLOR_BGR2GRAY)
MFS = CFAImageMFS(gray_image, q_list=np.linspace(-5, 5, 26))
df_mass, df_fit, df_spec = MFS.get_mfs()
MFS.plot(df_mass, df_fit, df_spec)
Fractal Dimensions of an Image
from FreeAeonFractal.FAImageFD import CFAImageFD from FreeAeonFractal.FAImage import CFAImage bin_image, threshold = CFAImage.otsu_binarize(gray_image) fd_bc = CFAImageFD(bin_image).get_bc_fd() fd_dbc = CFAImageFD(gray_image).get_dbc_fd() fd_sdbc = CFAImageFD(gray_image).get_sdbc_fd() CFAImageFD.plot(rgb_image, gray_image, bin_image, fd_bc, fd_dbc, fd_sdbc)
Local Alpha Map
MFS = CFAImageMFS(gray_image) alpha_map, info = MFS.compute_alpha_map() CFAImageMFS.plot_alpha_map(alpha_map)
Lacunarity Analysis
from FreeAeonFractal.FAImageLAC import CFAImageLAC calc = CFAImageLAC(gray_image, partition_mode="gliding") lac_result = calc.get_lacunarity() fit_result = calc.fit_lacunarity(lac_result) calc.plot(lac_result, fit_result)
Fourier Analysis
from FreeAeonFractal.FAImageFourier import CFAImageFourier
fourier = CFAImageFourier(rgb_image)
mag_disp, phase_disp = fourier.get_display_spectrum(alpha=1.5)
full_reconstructed = fourier.get_reconstruct()
fourier.plot(raw_magnitude_disp=mag_disp, raw_phase_disp=phase_disp,
full_reconstructed=full_reconstructed)
Multifractal Spectrum of a Time Series
from FreeAeonFractal.FASeriesMFS import CFASeriesMFS x = np.cumsum(np.random.randn(5000)) mfs = CFASeriesMFS(x, q_list=np.linspace(-5, 5, 21)) df_mfs = mfs.get_mfs() mfs.plot(df_mfs)
Command Line Usage
python demo.py --mode mfs --image ./images/face.png python demo.py --mode fd --image ./images/fractal.png python demo.py --mode alpha --image ./images/face.png python demo.py --mode lacunarity --image ./images/fractal.png python demo.py --mode fourier --image ./images/face.png python demo.py --mode series
demo.py Examples
Complete Python code from each --mode in demo.py.
mode=fd — Fractal Dimension
import cv2, time, numpy as np
from FreeAeonFractal.FAImageFD import CFAImageFD
from FreeAeonFractal.FAImage import CFAImage
rgb_image = cv2.cvtColor(cv2.imread('./images/face.png'), cv2.COLOR_BGR2RGB)
gray_image = cv2.cvtColor(rgb_image, cv2.COLOR_RGB2GRAY)
bin_image, threshold = CFAImage.otsu_binarize(gray_image)
max_scales = 32
# --- Single image ---
t0 = time.time()
fd_bc = CFAImageFD(bin_image, max_scales=max_scales).get_bc_fd(corp_type=-1)
fd_dbc = CFAImageFD(gray_image, max_scales=max_scales).get_dbc_fd(corp_type=-1)
fd_sdbc = CFAImageFD(gray_image, max_scales=max_scales).get_sdbc_fd(corp_type=-1)
print(f"Single (1) img: {time.time()-t0:.3f}s")
print(" BC:", fd_bc['fd'], " DBC:", fd_dbc['fd'], " SDBC:", fd_sdbc['fd'])
CFAImageFD.plot(rgb_image, gray_image, bin_image, fd_bc, fd_dbc, fd_sdbc)
# --- Batch (100 images) ---
t0 = time.time()
bc_list = CFAImageFD.get_batch_bc([bin_image]*100, max_scales=max_scales, with_progress=False)
dbc_list = CFAImageFD.get_batch_dbc([gray_image]*100, max_scales=max_scales, with_progress=False)
sdbc_list = CFAImageFD.get_batch_sdbc([gray_image]*100, max_scales=max_scales, with_progress=False)
print(f"Batch (100 imgs): {time.time()-t0:.3f}s")
print(f" BC[99]={bc_list[99]['fd']:.4f} DBC[99]={dbc_list[99]['fd']:.4f} SDBC[99]={sdbc_list[99]['fd']:.4f}")
CFAImageFD.plot(rgb_image, gray_image, bin_image, bc_list[99], dbc_list[99], sdbc_list[99])
mode=mfs — Multifractal Spectrum
import cv2, time, numpy as np
from FreeAeonFractal.FAImageMFS import CFAImageMFS
rgb_image = cv2.cvtColor(cv2.imread('./images/face.png'), cv2.COLOR_BGR2RGB)
gray_image = cv2.cvtColor(rgb_image, cv2.COLOR_RGB2GRAY)
q_list = np.linspace(-10, 10, 101)
# --- Single image ---
t0 = time.time()
MFS = CFAImageMFS(gray_image, q_list=q_list)
df_mass, df_fit, df_spec = MFS.get_mfs()
print(f"Single MFS: {time.time()-t0:.3f}s"); print(df_fit.head())
MFS.plot(df_mass, df_fit, df_spec)
# --- Batch (20 images) ---
t0 = time.time()
batch_results = CFAImageMFS.get_batch_mfs(
[gray_image]*20, with_progress=False, q_list=q_list, corp_type=-1,
bg_reverse=False, bg_threshold=0.01, bg_otsu=False, max_scales=80,
min_points=6, use_middle_scales=False, if_auto_line_fit=False,
fit_scale_frac=(0.3, 0.7), auto_fit_min_len_ratio=0.6, cap_d0_at_2=False)
df_mass1, df_fit1, df_spec1 = batch_results[0]
print(f"Batch MFS (20): {time.time()-t0:.3f}s"); print(df_fit1.head())
MFS.plot(df_mass1, df_fit1, df_spec1)
mode=alpha — Local Multifractal α-map
import cv2, time, numpy as np
from FreeAeonFractal.FAImageMFS import CFAImageMFS
rgb_image = cv2.cvtColor(cv2.imread('./images/face.png'), cv2.COLOR_BGR2RGB)
gray_image = cv2.cvtColor(rgb_image, cv2.COLOR_RGB2GRAY)
q_list = np.linspace(-5, 5, 51)
scales = list(range(1, 100))
# --- Single image ---
t0 = time.time()
MFS = CFAImageMFS(gray_image, q_list=q_list)
alpha_map, info = MFS.compute_alpha_map(scales=scales)
print(f"Single alpha_map: {time.time()-t0:.3f}s")
print(" alpha map:", alpha_map, "\n scale info:", info)
CFAImageMFS.plot_alpha_map(alpha_map)
# --- Batch (20 images) ---
t0 = time.time()
batch_alpha_map = CFAImageMFS.compute_alpha_map_batch([gray_image]*20, with_progress=False, scales=scales)
alpha_maps, infos = batch_alpha_map[0], batch_alpha_map[1]
print(f"Batch alpha_map (20): {time.time()-t0:.3f}s")
CFAImageMFS.plot_alpha_map(alpha_maps[0])
mode=lacunarity — Lacunarity Analysis
import cv2, time
from FreeAeonFractal.FAImageLAC import CFAImageLAC
rgb_image = cv2.cvtColor(cv2.imread('./images/fractal.png'), cv2.COLOR_BGR2RGB)
gray_image = cv2.cvtColor(rgb_image, cv2.COLOR_RGB2GRAY)
lacunarity = CFAImageLAC(gray_image, max_scales=256, with_progress=True)
# --- Single image ---
t0 = time.time()
lac_gray = lacunarity.get_lacunarity(corp_type=-1, use_binary_mass=False, include_zero=True)
fit_gray = lacunarity.fit_lacunarity(lac_gray)
print(f"Single lacunarity: {time.time()-t0:.3f}s")
print(" slope:", fit_gray["slope"], " R:", fit_gray["r_value"], " P:", fit_gray["p_value"])
lacunarity.plot(lac_gray, fit_gray)
# --- Batch (100 images) ---
t0 = time.time()
batchs = CFAImageLAC.get_batch_lacunarity(
[gray_image]*100, scales_mode="powers", partition_mode="gliding",
use_binary_mass=False, with_progress=False)
fits = CFAImageLAC.fit_batch_lacunarity(batchs)
print(f"Batch lacunarity (100): {time.time()-t0:.3f}s")
print(" slope:", fits[99]["slope"], " R:", fits[99]["r_value"])
lacunarity.plot(batchs[99], fits[99])
mode=fourier — Fourier Analysis
import cv2, numpy as np
from FreeAeonFractal.FAImageFourier import CFAImageFourier
rgb_image = cv2.cvtColor(cv2.imread('./images/face.png'), cv2.COLOR_BGR2RGB)
fourier = CFAImageFourier(rgb_image) # supports grayscale and RGB
raw_mag, raw_phase = fourier.get_raw_spectrum()
raw_mag_disp, raw_phase_disp = fourier.get_display_spectrum(alpha=1.5)
# Custom mask: keep odd-frequency components
h, w = raw_mag[0].shape
Y, X = np.ogrid[:h, :w]
mask = ((X % 2 == 1) & (Y % 2 == 1)).astype(np.uint8)
customized_mag_list = raw_mag * mask
customized_phase_list = raw_phase * mask
customized_mag_disp, customized_phase_disp = fourier.get_display_spectrum(
alpha=1.5, magnitude=customized_mag_list, phase=customized_phase_list)
full_reconstructed = fourier.get_reconstruct()
masked_reconstructed = fourier.extract_by_freq_mask(mask)
fourier.plot(raw_mag_disp, raw_phase_disp,
customized_mag_disp, customized_phase_disp,
full_reconstructed, masked_reconstructed)
print(masked_reconstructed)
mode=series — Series Multifractal Spectrum
import numpy as np from FreeAeonFractal.FASeriesMFS import CFASeriesMFS x = np.cumsum(np.random.randn(5000)) # random walk example mfs = CFASeriesMFS(x) df_mfs = mfs.get_mfs() mfs.plot(df_mfs) print(df_mfs)