flexmark java
1.0.0
Este documento proporciona una descripción general completa de flexmark-java, una implementación Java de alto rendimiento del analizador CommonMark Markdown. Detalla sus características, incluida la velocidad, la extensibilidad y el seguimiento detallado de la posición del origen, junto con instrucciones para un inicio rápido, extensiones disponibles y migración desde pegdown. El documento también cubre sus pautas de contribución y desarrollo continuo.
flexmark-java
flexmark-java es una implementación Java del analizador CommonMark (especificación 0.28) que utiliza el
bloques primero, líneas en línea después de la arquitectura de análisis de Markdown.
Sus puntos fuertes son la velocidad, la flexibilidad, el elemento fuente Markdown basado en AST con detalles del
posición de la fuente hasta los caracteres individuales de los lexemas que componen el elemento y
extensibilidad.
La API permite un control granular del proceso de análisis y está optimizada para analizar con una gran cantidad
Número de extensiones instaladas. El analizador y las extensiones vienen con muchas opciones para el analizador.
comportamiento y variaciones de representación HTML. El objetivo final es que el analizador y el renderizador puedan
imitar a otros analizadores con gran grado de precisión. Esto ahora está parcialmente completo con el
implementación de la emulación del procesador Markdown
La motivación para este proyecto fue la necesidad de reemplazar el analizador pegdown en mi Markdown Navigator.
complemento para IDE de JetBrains. pegdown tiene un gran conjunto de características pero su velocidad en general es menor
que ideal y para entradas patológicas se cuelga o prácticamente se cuelga durante el análisis.
️La versión 0.60.0 tiene cambios importantes debido a la reorganización, el cambio de nombre, la limpieza y
optimización de clases de implementación. Los cambios se detallan en
Versión-0.60.0-Cambios.
el último
Requisitos
Para las versiones 0.62.2 o inferiores, Java 8 o superior, compatible con Java 9+. Para las versiones 0.64.0 o
arriba, Java 11 o superior.
El proyecto está en Maven: com.vladsch.flexmark
El núcleo no tiene más dependencias que org.jetbrains:annotations:24.0.1. Para extensiones, consulte
descripción de la extensión a continuación.
La API todavía está evolucionando para adaptarse a nuevas extensiones y funcionalidades.
Inicio rápido
Para Maven, agregue flexmark-all como una dependencia que incluye el núcleo y todos los módulos al
siguiente muestra:
Fuente:
Muestra básica.java
Construyendo a través de Gradle
Construyendo con Android Studio
Configuraciones adicionales debido a archivos duplicados:
Puede encontrar más información en la documentación:
Ejemplos de uso en el hogar de Wiki
Detalles de la extensión
Extensiones de escritura
Ayudante de migración pegada
La clase PegdownOptionsAdapter convierte los indicadores pegdown Extensions.* en opciones de flexmark y
lista de extensiones. Pegdown Extensions.java se incluye por conveniencia y no se encuentran nuevas opciones
en pegado 1.6.0. Estos están ubicados en el módulo flexmark-profile-pegdown pero puedes tomar el
fuente de este repositorio: PegdownOptionsAdapter.java, Extensions.java y crea el tuyo propio
versión modificada según las necesidades de su proyecto.
Puede pasar sus indicadores de extensión a PegdownOptionsAdapter.flexmarkOptions(int) estático o usted
puede crear una instancia de PegdownOptionsAdapter y usar métodos convenientes para configurar, agregar y eliminar
banderas de extensión. PegdownOptionsAdapter.getFlexmarkOptions() devolverá una copia nueva de
DataHolder siempre con las opciones que reflejan indicadores de extensión vinculados.
La emulación predeterminada de flexmark-java pegdown utiliza un análisis de bloques HTML menos estricto que interrumpe una
Bloque HTML en una línea en blanco. Pegdown sólo interrumpe un bloque HTML en una línea en blanco si todas las etiquetas en
el bloque HTML está cerrado.
Para acercarse al comportamiento de análisis de bloques HTML original, utilice el método que toma un
argumento booleano estrictoHtml:
También está disponible una muestra con un solucionador de enlaces personalizado, que incluye un solucionador de enlaces para
cambiar las URL o los atributos de los enlaces y un renderizador de nodos personalizado si necesita anular el
enlace generado HTML.
flexmark-java tiene muchas más extensiones y opciones de configuración que
pegdown además de las extensiones disponibles en pegdown 1.6.0.
Extensiones disponibles a través de PegdownOptionsAdapter
Últimas incorporaciones y cambios
Reorganización importante y limpieza de código de la implementación en la versión 0.60.0, consulte
Versión-0.60.0-Cambios gracias al gran trabajo de
Alex Karezin puede obtener una descripción general de las dependencias de los módulos
con capacidad para profundizar en paquetes y clases.
Fusionar API para fusionar varios documentos de rebajas en uno solo
documento.
Extensión del renderizador Docx:
Manejo de nodos de atributos limitados
Módulo extensible de conversión de HTML a Markdown:
flexmark-html2md-convertidor. Muestra:
HtmlToMarkdownCustomizedSample.java
Compatibilidad del módulo Java9+
Referencias enumeradas compuestas
Extensión de referencias enumeradas para crear
Numeración legal de elementos y encabezamientos.
Extensión de macros para permitir que el contenido de rebajas arbitrario sea
insertado como bloque o elementos en línea, lo que permite utilizar elementos de bloque donde solo están en línea
Los elementos están permitidos por sintaxis.
Markdown con sabor a GitLab para analizar y
renderizando extensiones de rebajas de GitLab.
Módulo OSGi cortesía de Dan Klco (GitHub @klcodanr)
Etiquetas multimedia Extensión del transformador de enlace multimedia cortesía
Cornelia Schultz (GitHub @CorneliaXaos) transforma enlaces
usando prefijos personalizados para etiquetas HTML5 de audio, inserción, imagen y video.
API de ayuda de traducción para reducir las rebajas de traducción
documentos más fácilmente.
Advertencia Para crear contenido lateral con estilo de bloque. Para
documentación completa, consulte la Extensión de Admoniciones, Material para MkDocs
documentación.
Referencia enumerada para crear enumerados
referencias para figuras, tablas y otros elementos de rebajas.
Atributos para analizar atributos de la forma {nombre nombre=valor nombre='valor' nombre="valor" #id .class-name} atributos.
Transformador de enlace integrado de YouTube
gracias a Vyacheslav N. Boyko (GitHub @bvn13) transforma enlaces simples a videos de youtube en
iframe de vídeo incrustado HTML.
Docx Converter usando la biblioteca docx4j. Cómo utilizar:
Ejemplo de DocxConverter, cómo personalizar:
Personalización del renderizado Docx
El desarrollo de este módulo fue patrocinado por
Instituto Johner GmbH.
Actualice la biblioteca para que sea compatible con CommonMark (especificación 0.28) y agregue
ParserEmulationProfile.COMMONMARK027 y ParserEmulationProfile.COMMONMARK028 para permitir
seleccionando opciones de versión de especificaciones específicas.
API de representación de nodos personalizados con capacidad para invocar la representación estándar para un nodo anulado.
permitiendo representaciones de nodos personalizados que solo manejan casos especiales y permiten que el resto se represente como
habitual. solucionador de enlaces personalizado
Gfm-Problemas y
Extensiones de Gfm-Users para analizar y renderizar #123 y
@nombre de usuario respectivamente.
Opción de análisis profundo de bloques HTML para un mejor manejo de etiquetas de texto sin formato que aparecen después de otras etiquetas.
y para compatibilidad con el análisis de bloques HTML vinculados.
Módulo flexmark-all que incluye: core, todas las extensiones, formateador, JIRA y YouTrack
convertidores, módulo de perfil pegdown y conversión de HTML a Markdown.
Módulo de salida de PDF
Salida de PDF usando Open HTML To PDF
Tipográfica implementada
Extensión de macros XWiki
Etiquetas de Jekyll
HTML para rebajar
Complemento generador de páginas de rebajas de Maven
Módulo Markdown Formatter para generar AST como descuento con
opciones de formato.
Tablas para el formateador Markdown
con ancho de columna y alineación de tablas de rebajas:
Lanzamientos, correcciones de errores, mejoras y soporte
Utilizo flexmark-java como analizador del complemento Markdown Navigator para IDE de JetBrains. tiendo a
utilice la versión más reciente e inédita para corregir errores u obtener mejoras. Entonces, si encuentra un error que sea
un obstáculo para su proyecto o ve un error en la página de problemas de github marcado como solucionado para la próxima versión que está afectando su proyecto, hágamelo saber y podré solucionarlo de inmediato
haga una nueva versión para solucionar su problema. De lo contrario, dejaré que se corrijan errores y se realicen mejoras.
Acumula pensando que a nadie le afecta lo que ya está arreglado.
Los puntos de extensión en la API son muchos y numerosos
Hay muchas opciones de extensión en la API con su uso previsto. Un buen comienzo suave es el
Módulo flexmark-java-samples que tiene muestras simples solicitadas
extensiones. El siguiente mejor lugar es la fuente de una extensión existente que tenga una sintaxis similar.
a lo que quieras agregar.
Si su extensión se alinea con la API correcta, la tarea suele ser muy breve y sencilla. si tu
la extensión utiliza la API de forma no deseada o no sigue el mantenimiento esperado
protocolos, puede que le resulte una batalla cuesta arriba con un nido de ratas de manejo de condiciones y
corregir un error solo conduce a la creación de otro.
Generalmente, si se necesitan más de unas pocas docenas de líneas para agregar una extensión simple, entonces
Lo están haciendo mal o a la API le falta un punto de extensión. Si miras todos los
extensiones implementadas, verá que la mayoría son unas pocas líneas de código además del texto estándar
dictado por la API. Ese es el objetivo de esta biblioteca: proporcionar un núcleo extensible que haga
escribir extensiones es muy sencillo.
Las extensiones más grandes son flexmark-ext-tables y flexmark-ext-spec-example, la carne de
ambos tienen alrededor de 200 líneas de código. Puedes utilizarlos como guía para estimar el tamaño de tu
extensión.
Mi propia experiencia al agregar extensiones muestra que a veces es mejor un nuevo tipo de extensión.
abordado con una mejora de API para que su implementación sea perfecta, o corrigiendo un error que
no era visible antes de que la extensión enfatizara la API de la manera correcta. Tu intención
la extensión puede ser la que requiera tal enfoque.
No dudes en abrir un problema si no encuentras la respuesta.
La conclusión es: si desea implementar una extensión o función, no dude en
Abra un problema y le daré sugerencias sobre la mejor manera de solucionarlo. Puede que te ahorre mucho
de tiempo permitiéndome mejorar la API para abordar las necesidades de su extensión antes de que ponga muchas
esfuerzo infructuoso en ello.
Le pido que se dé cuenta de que soy jefe de cocina y lavador de botellas en este proyecto, sin
un ápice de habilidades de fusión mental vulcana. Le pido que describa lo que desea implementar.
porque no puedo leer tu mente. Por favor, haga un trabajo de reconocimiento en torno a la fuente.
código y documentación porque no puedo transferirte lo que sé, sin tu voluntad
esfuerzo.
Consulta disponible
Si tiene una aplicación comercial y no desea escribir las extensiones usted mismo o desea
para reducir el tiempo y el esfuerzo de implementar extensiones e integrar flexmark-java, siéntase
libre de contactarme. Estoy disponible en forma de consultoría/contratación.
Emulación del procesador Markdown
A pesar de su nombre, commonmark no es ni un superconjunto ni un subconjunto de otros tipos de rebajas.
Más bien, propone una especificación de sintaxis estándar e inequívoca para el "núcleo" original.
Markdown, introduciendo así efectivamente otro sabor más. Mientras que flexmark es por defecto
Compatible con commonmark, su analizador se puede modificar de varias maneras. Los conjuntos de ajustes necesarios para
emular los analizadores de rebajas más utilizados están disponibles en flexmark como
Perfiles de emulación del analizador.
Como lo implica el nombre ParserEmulationProfile, es sólo el analizador el que se ajusta al
sabor de rebajas específico. La aplicación del perfil no agrega funciones más allá de las disponibles en
marca común. Si desea utilizar flexmark para emular completamente el comportamiento de otro procesador de rebajas,
debe ajustar el analizador y configurar las extensiones de Flexmark que proporcionan funciones adicionales
funciones disponibles en el analizador que desea emular.
Una reescritura del analizador de listas para controlar mejor la emulación de otros procesadores de rebajas según
La emulación de procesadores Markdown está completa. Adición de
Los ajustes preestablecidos del procesador para emular el comportamiento de procesamiento de rebajas específico de estos analizadores están en un
Lista corta de cosas por hacer.
Algunas familias de emulación hacen un mejor trabajo al emular a su objetivo que otras. La mayoría de
el esfuerzo se dirigió a emular cómo estos procesadores analizan Markdown estándar y enumeran
análisis relacionado específicamente. Para procesadores que extienden Markdown original, deberá agregar
aquellas extensiones que ya están implementadas en flexmark-java para el generador Parser/Renderer
opciones.
Las extensiones se modificarán para incluir sus propios ajustes preestablecidos para una emulación de procesador específica, si
ese procesador tiene implementada una extensión equivalente.
Si encuentra una discrepancia, abra un problema para poder solucionarlo.
Se implementan las principales familias de procesadores y algunos miembros de la familia también:
perfiles para encapsular detalles de configuración para variantes dentro del
La familia se agregó en 0.11.0:
Historia y motivación
flexmark-java es una bifurcación del proyecto commonmark-java, modificada para generar un AST que
refleja todos los elementos en la fuente original, seguimiento completo de la posición de la fuente para todos los elementos
en AST y generación más sencilla de JetBrains Open API PsiTree.
La API se cambió para permitir un control más granular del proceso de análisis y se optimizó para
analizando con una gran cantidad de extensiones instaladas. El analizador y las extensiones vienen con muchos
opciones de ajuste para el comportamiento del analizador y variaciones de representación HTML. El objetivo final es tener la
El analizador y el renderizador podrán imitar a otros analizadores con gran grado de precisión.
La motivación para esto fue la necesidad de reemplazar el analizador pegdown en el complemento Markdown Navigator.
pegdown tiene un gran conjunto de características, pero su velocidad en general no es ideal y para
la entrada patológica se bloquea o prácticamente se bloquea durante el análisis.
commonmark-java tiene una excelente arquitectura de análisis que es fácil de entender y ampliar.
El objetivo era garantizar que agregar el seguimiento de la posición de la fuente en el AST no cambiara la facilidad
de analizar y generar el AST más de lo absolutamente necesario.
Las razones para elegir commonmark-java como analizador son: velocidad, facilidad de comprensión, facilidad de
extensión y velocidad. Ahora que he reelaborado el núcleo y he añadido algunas extensiones, estoy extremadamente
satisfecho con mi elección.
Otro objetivo era mejorar la capacidad de las extensiones para modificar el comportamiento del analizador para que cualquier
El dialecto de rebajas podría implementarse a través del mecanismo de extensión. Opciones extensibles
Se agregó API para permitir la configuración de todas las opciones en un solo lugar. Uso de analizador, renderizador y extensiones.
estas opciones de configuración, incluida la desactivación de algunos analizadores de bloques principales.
Este es un trabajo en progreso con muchos cambios de API. No se intenta mantener la API hacia atrás.
compatibilidad con el proyecto original y hasta que el conjunto de funciones esté prácticamente completo, ni siquiera
versiones anteriores de este proyecto.
Comparación de características
(1)
entrada patológica flexmark-java de 100.000 [análisis en 68 ms, 100.000] en 57 ms, 100.000
análisis anidado [] en 55 ms
(2)
entrada patológica commonmark-java de 100.000 [análisis en 30 ms, 100.000] en 30 ms, 100.000
análisis anidado [] en 43 ms
(3)
entrada patológica pegada de 17 [análisis en 650 ms, 18 [en 1300 ms
Progreso
Estoy muy satisfecho con la decisión de cambiar al analizador basado en commonmark-java por mi cuenta.
proyectos. A pesar de que tuve que hacerle una cirugía mayor en sus entrañas para obtener la posición completa de la fuente.
seguimiento y AST que coincide con los elementos de origen, es un placer trabajar con él y ahora es un
placer de extender. Si no necesita el elemento de nivel de fuente AST o el resto de lo que flexmark-java
agregado y CommonMark es su analizador de rebajas objetivo, le recomiendo que utilice
commonmark-java ya que es una excelente opción para sus necesidades y su rendimiento no
sufrir por la sobrecarga de funciones que no utilizará.
Puntos de referencia
Último, 28 de enero de 2017 flexmark-java 0.13.1, intellij-markdown de CE EAP 2017, commonmark-java
0.8.0:
Ratios de lo anterior:
Debido a que estos dos archivos representan la entrada patológica para pegdown, ya no los ejecuto como
parte del índice de referencia para evitar sesgos en los resultados. Los resultados están aquí para la posteridad.
Ratios de lo anterior:
Contribuyendo
¿Se aceptan solicitudes de extracción, problemas y comentarios? Para solicitudes de extracción:
Licencia
Copyright (c) 2015-2016 Atlassian y otros.
Copyright (c) 2016-2023, Vladimir Schneider,
Licencia BSD (2 cláusulas), consulte el archivo LICENSE.txt.
ejemplo:
Renderizador Mitsuba 3
Documentación | Vídeos tutoriales | linux | Mac OS | ventanas | PyPI |
|---|---|---|---|---|---|
️
Advertencia
️
Actualmente hay una gran cantidad de trabajo indocumentado e inestable en
la rama master . Le recomendamos encarecidamente que utilice nuestro
último lanzamiento
hasta nuevo aviso.
Si ya desea probar los próximos cambios, eche un vistazo a
esta guía de portabilidad.
Debería cubrir la mayoría de las nuevas funciones y los cambios importantes que se avecinan.
Introducción
Mitsuba 3 es un sistema de renderizado de luz directa e inversa orientado a la investigación
Simulación de transporte desarrollada en EPFL en Suiza.
Consiste en una biblioteca central y un conjunto de complementos que implementan funciones.
que van desde materiales y fuentes de luz hasta algoritmos de renderizado completos.
Mitsuba 3 es reorientable : esto significa que las implementaciones subyacentes y
Las estructuras de datos pueden transformarse para realizar varias tareas diferentes. Para
Por ejemplo, el mismo código puede simular transporte RGB escalar (clásico de un rayo a la vez)
o transporte espectral diferencial en la GPU. Todo esto se basa en
Dr.Jit, un compilador especializado justo a tiempo (JIT) desarrollado específicamente para este proyecto.
Características principales
Multiplataforma : Mitsuba 3 ha sido probado en Linux ( x86_64 ), macOS
( aarch64 , x8664 ) y Windows ( x8664 ).
Alto rendimiento : el compilador Dr.Jit subyacente fusiona el código de renderizado
en núcleos que logran un rendimiento de última generación utilizando
un backend LLVM dirigido a la CPU y un backend CUDA/OptiX
dirigido a GPU NVIDIA con aceleración de hardware de trazado de rayos.
Python primero : Mitsuba 3 está profundamente integrado con Python. materiales,
Se pueden desarrollar texturas e incluso algoritmos de renderizado completos en Python.
que el sistema compila JIT (y opcionalmente diferencia) sobre la marcha.
Esto permite la experimentación necesaria para la investigación en gráficos por ordenador y
otras disciplinas.
Diferenciación : Mitsuba 3 es un renderizador diferenciable, lo que significa que
Puede calcular derivadas de toda la simulación con respecto a la entrada.
parámetros como la pose de la cámara, la geometría, los BSDF, las texturas y los volúmenes. Él
implementa algoritmos de representación diferenciables recientes desarrollados en EPFL.
Espectral y polarización : Mitsuba 3 se puede utilizar como monocromático
renderizador, renderizador basado en RGB o renderizador espectral. Cada variante puede
Opcionalmente, tenga en cuenta los efectos de la polarización si se desea.
Vídeos tutoriales, documentación.
Hemos grabado varios vídeos de YouTube que proporcionan una suave introducción.
Mitsuba 3 y Dr.Jit. Más allá de esto puedes encontrar cuadernos Juypter completos.
que cubre una variedad de aplicaciones, guías prácticas y documentación de referencia
en readthedocs.
Instalación
Proporcionamos ruedas binarias precompiladas a través de PyPI. Instalar Mitsuba de esta manera es tan sencillo como ejecutar
instalar pip mitsuba
en la línea de comando. El paquete Python incluye trece variantes por defecto:
scalar_rgb
scalar_spectral
scalarspectralpolarized
llvmadrgb
llvmadmono
llvmadmono_polarized
llvmadspectral
llvmadspectral_polarized
cudaadrgb
cudaadmono
cudaadmono_polarized
cudaadspectral
cudaadspectral_polarized
Los dos primeros realizan la simulación clásica de un rayo a la vez usando un RGB
o representación de color espectral, mientras que los dos últimos se pueden utilizar para representación inversa.
renderizado en la CPU o GPU. Para acceder a variantes adicionales, deberá
compilar una versión personalizada de Dr.Jit usando CMake. Por favor vea el
documentación
para obtener detalles sobre esto.
Requisitos
Python >= 3.8
(opcional) Para cálculo en la GPU: Nvidia driver >= 495.89
(opcional) Para cálculo vectorizado/paralelo en la CPU: LLVM >= 11.1
Uso
A continuación se muestra un ejemplo sencillo de "Hola mundo" que muestra lo sencillo que es representar un
escena usando Mitsuba 3 de Python:
# Importar la biblioteca usando el alias "mi" importar mitsuba como mi # Establecer la variante de renderermi.setvariant('scalarrgb')# Cargar una escena = mi.loaddict(mi.cornellbox())# Renderizar la escenaimg = mi. render(scene)# Escribe la imagen renderizada en un archivo EXRmi.Bitmap(img).write('cbox.exr')Se pueden encontrar tutoriales y cuadernos de ejemplo que cubren una variedad de aplicaciones.
en la documentación.
Acerca de
Este proyecto fue creado por Wenzel Jakob.
Funciones y/o mejoras significativas al código fueron aportadas por
Sébastien Speierer,
Nicolás Roussel,
Merlín Nimier-David,
Delio Vicini,
Tizian Zeltner,
Bautista Nicolet,
Miguel Crespo,
Vicente Leroy y
Ziyi Zhang.
Cuando utilice Mitsuba 3 en proyectos académicos, cite:
@software{Mitsuba3,title = {Mitsuba 3 renderer},autor = {Wenzel Jakob y Sébastien Speierer y Nicolas Roussel y Merlin Nimier-David y Delio Vicini y Tizian Zeltner y Baptiste Nicolet y Miguel Crespo y Vincent Leroy y Ziyi Zhang},nota = {https://mitsuba-renderer.org},versión = {3.1.1},año = 2022} 
