PDFSyntax - PDF dosyalarının iç yapısının HTML ile görselleştirilmesi

 (github.com/desgeeko)
2 puan yazan GN⁺ 2025-02-11 | 1 yorum | WhatsApp'ta paylaş
  • PDFSyntax, PDF Specification’ın 7. bölümü “Syntax”a odaklanan bir Python kütüphanesidir; PDF dosyalarının iç belge yapısını bayt düzeyine kadar incelemek ve dönüştürmek için kullanılır
  • Baştan sona saf Python ile yazılmış, bağımlılığı olmayan hafif bir kütüphanedir; sadeliğe ve değişmezliğe önem verir
  • Varsayılan düzenleme yöntemi, PDF belirtiminin izin verdiği yıkıcı olmayan artımlı güncellemedir; değişiklik bölümlerini özgün dosyanın sonuna ekler ve geri sarma ya da tek bir revizyonda birleştirme yapılabilir
  • CLI; overview, disasm, text, fonts, browse gibi komutlar sunar; browse, PDF kaynağını okunaklı biçimde çıktılar ve köprüler içeren statik HTML ile iç yapıda gezinmeyi sağlar
  • Şu anda beta kalitesinde, geliştirme aşamasındaki bir projedir; API her an değişebilir. MIT lisanslıdır ancak henüz dış katkı kabul etmemektedir

PDF iç yapısını inceleme ve dönüştürme

  • PDFSyntax, PDF dosyalarının iç yapısını incelemek ve dönüştürmek için kullanılan bir Python kütüphanesidir
  • Portable Document Format (PDF) Specification’ın 7. bölümü olan “Syntax”a odaklanır
  • Belge yapısı yönetimini bayt seviyesine kadar gerçekleştirerek şu amaçlarla kullanılır
    • Meta verilere erişim
    • Sayfa döndürme
    • PDF okuma/yazma işlemleri
    • İç nesnelere erişim ve bunları işleme

Tasarım yönü

  • İç fonksiyonlar, PDF okuma/yazma işlemleri için bir API araç seti olarak sunulur
  • Bazı özellikler terminalde veya tarayıcıda kullanılabilmesi için CLI olarak da sağlanır
  • Kütüphane saf Python ile yazılmıştır ve harici bağımlılığı yoktur
  • Sadeliğe ve değişmezliğe önem verir
  • Varsayılan düzenleme yöntemi, özgün dosyanın doğrudan üzerine yazmak yerine değişiklikleri özgün dosyanın sonuna ekleyen artımlı güncellemedir
    • Gerekirse revizyonlar geri sarılabilir
    • Tüm revizyonlar tek bir revizyonda birleştirilebilir

Kurulum ve CLI kullanımı

  • PyPI üzerinden kurulabilir
pip install pdfsyntax
  • CLI’nin temel kullanım biçimi şöyledir
pdfsyntax COMMAND FILE
  • Kaynaktan kurulduysa daha uzun biçimde çalıştırılabilir
python3 -m pdfsyntax COMMAND FILE
  • Hızlı PDF analizi için başlıca komutlar şunlardır
    • overview: yapı ve meta veriler hakkında metin bilgisi çıktılar
    • disasm: dosya yapısı dökümünü terminale çıktılar
    • text: taranmış gibi mekânsal yerleşimi koruyan çıkarılmış metni çıktılar
    • fonts: kullanılan fontların listesini çıktılar
    • browse: PDF kaynağını okunaklı biçimde çıktılar ve köprüler eklenmiş statik HTML oluşturarak iç yapının keşfedilmesini destekler

API kullanım biçimi

  • PDFSyntax çoğunlukla basit fonksiyonlardan oluşur
  • readfile ile PDF okunabilir, metadata ile meta veriler Python dict biçiminde alınabilir
>>> from pdfsyntax import readfile, metadata
>>> doc = readfile("samples/simple_text_string.pdf")
>>> metadata(doc)
  • Doc nesnesi, belgenin iç durumunu saklayan neredeyse tek özel sınıftır
    • Özgün dosyadan önbelleğe alınmış veya memoize edilmiş içerik
    • İçerik ekleme, değiştirme ve silme değişiklikleri
    • Artımlı güncellemeyle izlenen değişiklik geçmişi
  • Aynı metadata fonksiyonu Doc nesnesinin metodu olarak da kullanılabilir
>>> doc.metadata()
  • get_object, update_object gibi düşük seviyeli fonksiyonlarla belgenin iç nesnelerine doğrudan erişilebilir ve bunlar işlenebilir
  • rotate gibi yüksek seviyeli fonksiyonlar da sunulur
>>> from pdfsyntax import rotate, writefile
>>> doc180 = rotate(doc, 180)
  • Döndürme örneğinde özgün nesne değiştirilmez; devam eden yön değişikliğini içeren yeni bir nesne oluşturulur
  • Değiştirilmiş PDF, writefile ile diske yazılabilir
>>> writefile(doc180, "rotated_doc.pdf")
  • Ortaya çıkan dosya, özgün içeriğin arkasına yeni bir bölüm eklenmiş biçimdedir; bu bölüm kesilip çıkarılırsa değişiklik geri alınabilir

Mevcut durum ve katkı politikası

  • Proje geliştirme aşamasındadır ve beta kalitesinde yazılımdır
  • API her an değişebilir
  • Sonraki işler listesinde şu maddeler yer alır
    • Sayfa kırpma ve birleştirme
    • Kayıpsız sıkıştırma
    • Daha fazla filtre
    • Metin çıkarma iyileştirmeleri
    • Düzen algılama ile metin çıkarmayı güçlendirme
  • PDFSyntax MIT lisanslıdır
  • Şu anda dış katkı kabul etmemektedir
    • Kişisel bir projedir ve zaman sınırlıdır
    • Önce yeni özelliklere ve refactoring yol haritasına odaklanılacak, kararlı hale geldikten sonra katkılar kabul edilecektir

İlgili okumalar

1 yorum

 
GN⁺ 2025-02-11
Hacker News yorumları

  • Uzun zaman önce çeşitli PDF'lerden veri çıkarma işi bana verilmişti; sayfadaki karakter yerleşimini ve tüm öğelerin sınır kutularını görselleştiren bir araç yapmıştım.
    Sonunda proje tamamen başarısız oldu; beklenen sonucu vermediği için bazıları sinirlendi.
    Şimdi olsa PDF'den veri çıkarmada LLM yeteneklerinden yararlanma yoluna %100 giderdim. O zaman böyle bir seçenek yoktu.

    • Rastgele bir PDF'den veri ayrıştırmak neredeyse lanetli bir görev. PDF'lerin içinde görseller de olabildiği için doğrudan JPEG'i hedef almakla benzer.
      Beklentiye bağlı olarak OCR ile epey yol alınabilir, ama benim deneyimime göre her zaman tam ihtiyaç duyulan seviyenin az gerisinde kalıyor.
    • LLM, sayfadan çıkarılan karakterlerin sırasını doğru kurmaya yardımcı olabilir; ancak asıl içeriği elde etmek hâlâ zor.
      Birçok kez gördüğüm örneklerde metindeki harfler ASCII gibi bir eşlemesi olmayan özel yazı tipi glifleri olabiliyor ya da özellikle CAD çıktılarında sık görüldüğü gibi harf şekilleri çizgilerle çizilmiş olabiliyor.
      Bu durumda çıkarılabilecek tanımlanabilir bir metin olmadığından, sonunda sayfayı OCR ile yeniden kontrol etmek gerekiyor.
    • Önceki iş yerimde benzer bir şey yaşamıştım; kural tabanlı ayrıştırma yaklaşımını düzgün yapmak gerçekten zor ve uç durumlarda sık sık başarısız oluyordu.
      Biz https://runtrellis.com/ üzerinde LLM ve görsel dil modellerine dayalı bir PDF işleme hattını sıfırdan inşa ediyoruz; zorlu PDF'lerde bile neredeyse %100'e yakın doğruluk gördük.
      Kilit nokta, sonuçları çapraz doğrulamak için kural tabanlı motoru referans verilerle birlikte kullanmak.
    • Uzun zaman önce PDF'den 2D CAD çizimleri çıkarıp bunları tam 3D'ye dönüştürme işi yapmıştım; oldukça eğlenceliydi.
    • pdfjs bu tür işlerin hepsini yapıyor ve oldukça sağlam. Yakın zamanda 10 yıllık banka ekstrelerinden tablo verisi çıkarmak için kullandım.

  • Oldukça harika. Eski iş yerimde bu olsaydı muhtemelen çok kullanırdım.
    İdeal olarak https://lapo.it/asn1js/ gibi, dosyayı bıraktığınızda tüm işlemleri yerelde yapan bir şey olsa iyi olurdu.

  • PDF'den veri çıkaran kodlarla uğraşma “ayrıcalığı” sayesinde, bir süredir PDF hata ayıklamak için iText RUPS'ın ücretsiz sürümünü kullanıyordum.
    Buradaki iç denetim özellikleri daha güçlü görünüyor; bu yüzden çok iyi olabilir. Bir denemeyi düşünüyorum.

  • GitHub'da benzer bir proje olduğunu hatırlıyorum. Verilen bir şemaya göre rastgele ikili veriyi görselleştirebiliyordu; sanırım TCP/IP örneği vardı.

    • https://kaitai.io/ olabilir mi?
      Bu iş için çok iyi görünüyordu, ama son projemde serileştirme de gerektiği için kullanmadım.
    • HexFiend'de de ikili veri görselleştirmek için bir şablon söz dizimi var. Tcl tabanlı.
      https://github.com/HexFiend/HexFiend/blob/master/templates/T...
    • Bu bağlamda “rastgele” sözcüğüne dikkat etmek gerek.
      İlginçtir, ben böyle dosya biçimi tanımlayıcılarını denerken PDF'yi “Hello World” olarak kullanıyorum; çünkü PDF belirtimi fazlasıyla tuhaf.
      Tanımlama dili PDF'in düzenini doğru ifade edebiliyorsa kesinlikle iyi tasarlanmış sayılabilir.
      Şimdiye kadar, bildirimsel moddan çıkıp “sonra şu kodu çalıştır” diyebilenler dışında pek şansım olmadı.

  • Bu, adli bilişim ve filigran bulma için de kullanışlı olur.

    • İlginç görünüyor. Pek bilmediğimden soruyorum: Bunu filigran algılamada nasıl kullanabiliriz? Aynı yöntemle imza da algılanabilir mi?

  • İyi görünüyor.
    PDF'in tüm baytları gösterilse daha da iyi olurdu. endobj ve xref görünmüyor gibi.

    • Evet, yakında düzelteceğim.

  • Bu bir tarayıcı kütüphanesi olarak çıksa gerçekten harika olurdu. Dosyayı sürükleyip bırakıp içini görebilmek yeterli. Yine de etkileyici.

    • Tarayıcı uzantısından mı bahsediyorsun? Kabalık etmek istemiyorum; doğru anladığımdan emin olmak istiyorum.

  • İyi yapılmış. Çok kullanışlı bir güvenlik önizleme aracı. PDF baş belası.

  • Görselleştirmeyi yapan UI aracının bir kütüphane olup olmadığını merak ediyorum.
    UI biçimini gerçekten beğendim; video bayt akışlarını parçalarına ayırıp hata ayıklamak için de kullanmak isterdim.
    Düzenleme: Aslında epey basitmiş. CSS'i iyi kullanmış! https://github.com/desgeeko/pdfsyntax/blob/main/docs/simple_...

    • Evet. Sadelik benim için önemli; temel HTML ve CSS'in sunduğu etkileşim benim kullanım senaryom için yeterli :)

  • Benzer bağlamda, PDF neden hâlâ yerini başka bir şeye bırakmadı? XPS, DjVu, XHTML(EPUB) var; ama hepsi farklı kullanım senaryolarını, örneğin paketlenmiş HTML dosyalarını hedefliyor gibi.
    Benim istediğim, Adobe'nin hantallığı olmadan başka dosyaları ve meta verileri gömebilen basit bir belge biçimi.
    Sayfa içinde hiperlink verilebilmeli, yazı boyutu değişse bile metin taşmamalı ve tutarlı şekilde yazdırılabilmeli.

    • PDF'in düzenleme, cihaz üzerinde okuma ve sunum bilgisinden ziyade anlamsal bilgi çıkarma açısından “talihsiz” bir biçim olmasının nedeninin Adobe'nin suçu ya da hantallığı olduğunu düşünmüyorum.
      PDF bir veri biçimi değil, sayfa tanımlama biçimi; yani farklı işletim sistemleri, yazılımlar, yazıcılar ve kesin kâğıt boyutları kullanılsa bile aynı “sayfa”yı yazdırabilme ihtiyacından doğan kararların toplamı.
      PDF'in uzun süre dayanmasının başlıca nedeni, pek çok şeyin belge paradigması, yani “belge”yi “birkaç kâğıt yaprağından oluşan bir deste” olarak görme biçimi üzerinde dönmesi olabilir.
      Hastane ziyareti sonrası özetinden araç tescil belgesine kadar, zaten kâğıt üzerinde makul görünen ve tam oturacak şekilde seçilmiş belirli bir görsel sunuma sahipler.
      HTML, örneğin görselleri ve CSS'i veri URL'leriyle içine koyup bağımsız çalışabilir hâle getirilmiş bir biçim, ya da ePub çoğu açıdan daha iyi olabilir.
      Ancak hedefleri o kadar farklı ki, bugün PDF üreten kişileri böyle bir geçişe ikna etmeye giderseniz, içeriğin cihazdan cihaza biraz farklı göründüğü ve ayarlara göre sayfa sonlarının bile değiştiği yönünde şikâyetler duyarsınız.
      Bununla ilgili ilginç bir nokta da, Google Docs'un bile yazdırılma ya da PDF'e dönüştürülme olasılığı yarıdan çok daha az gibi görünmesine rağmen varsayılanının sayfa modu olması; “sayfasız” mod değil.
      “Sayfasız” mod, sıradan bir web sayfası gibi pencereye uyar ve tek, kesintisiz bir yüzeyde sonsuza dek kaydırılır; bu yüzden çok daha kullanışlıdır.
    • Kullanım senaryosu farklı.
      “Metin taşmasın” gereksinimi pek çok ayrıntıyı beraberinde getirir.
      PDF'de metindeki her harf, karakter ve glifin sayfa üzerinde, hatta bazen sayfanın dışında kesin bir x,y konumu olabilir.
      Bu yüzden çevresinde ne olursa olsun içerik hassas biçimde yerleştirilebilir. PDF kullanan uygulamanın öğeleri doğru konumlandırması ve harf ya da sözcük satır kırılmasını uygulaması gerekir.
      XPS, PDF'i yeniden gerçekleştirmeye en çok yaklaşan şeydi; ancak Microsoft diğer aktörlerden yeterli destek alamadığı için sessizce kayboldu.
    • Yakın zamana kadar bilmediğim PDF'le ilgili ilginç bir nokta, PDF'in PostScript'in bir alt kümesi olması ve bunun da bir ölçüde ağırlığın nedeni olması.
      PostScript tuhaf olsa da eksiksiz bir programlama dili; PDF ise öyle değil. Yani Turing-tam değil.
      PDF kontrol akışını desteklemez; bu yüzden PostScript'te basit bir döngüyle ifade edilebilecek şeyler PDF'de açılarak bir dizi basit bildirim ya da ifade olarak saklanmak zorundadır.
      Avantajı, PDF'i render etmek için eksiksiz bir program yorumlayıcısına ihtiyaç olmamasıdır.
    • Böyle bir sohbet başlar başlamaz LaTeX cephesi ortaya çıkar ve standarda anlamlı katkı yapabilecek herkes o tartışmaya takılıp kalır.
    • Bir neden de diğer biçimlerden hiçbirinin olduğu hâliyle ticari baskıya uygun olmamasıdır.